forked from Open-EO/openeo-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
openapi.yaml
7723 lines (7386 loc) · 303 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.2
info:
title: geodatacube API
version: 1.0.0-beta
description: |-
The geodatacube API specification for interoperable cloud-based processing of large Earth observation datacubes.
**Conformance class**: `https://api.geodatacube.example/1.0.0-beta`
# API Principles
## Language
In the specification the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174.html).
## Casing
Unless otherwise stated the API works **case sensitive**.
All names SHOULD be written in snake case, i.e. words are separated with one underscore character (`_`) and no spaces, with all letters lower-cased. Example: `hello_world`. This applies particularly to endpoints and JSON property names. HTTP header fields are generally case-insensitive according to [RFC 7230](https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2) and in the specification we follow their respective casing conventions, e.g. `Content-Type` or `GDC-Identifier`, for better readability and consistency.
## HTTP / REST
This uses [HTTP REST](https://en.wikipedia.org/wiki/Representational_state_transfer) [Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2) for communication between client and back-end server.
Public APIs MUST be available via HTTPS only.
Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first-level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires to send the whole JSON object defined by the first-level property.
Naming of endpoints follow the REST principles. Therefore, endpoints are centered around resources. Resource identifiers MUST be named with a noun in plural form except for single actions that can not be modelled with the regular HTTP verbs. Single actions MUST be single endpoints with a single HTTP verb (POST is RECOMMENDED) and no other endpoints beneath it.
The API makes use of [HTTP Content Negotiation](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-negotiation),
including, but not limited to, the request headers `Accept`, `Accept-Charset` and `Accept-Language`.
### JSON
The API uses JSON for request and response bodies whenever feasible. Services use JSON as the default encoding. Other encodings can be requested using HTTP Content Negotiation ([`Accept` header](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept)). Clients and servers MUST NOT rely on the order in which properties appear in JSON. To keep the response size small, lists of resources (e.g. the list of batch jobs) usually should not include nested JSON objects, if this information can be requested from the individual resource endpoints (e.g. the metadata for a single batch job).
### Charset
Services use [UTF-8](https://en.wikipedia.org/wiki/UTF-8) as the default charset if not negotiated otherwise with HTTP Content Negotiation ([`Accept-Charset` header](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-charset)).
## Web Linking
The API is designed in a way that to most entities (e.g. collections and processes) a set of links can be added. These can be alternate representations, e.g. data discovery via OGC WCS or OGC CSW, references to a license, references to actual raw data for downloading, detailed information about pre-processing and more. Clients should allow users to follow the links.
Whenever links are utilized in the API, the description explains which relation (`rel` property) types are commonly used.
A [list of standardized link relations types is provided by IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml) and the API tries to align whenever feasible.
Some very common relation types - usually not mentioned explicitly in the description of `links` fields - are:
1. `self`: which allows link to the location that the resource can be (permanently) found online.This is particularly useful when the data is data is made available offline, so that the downstream user knows where the data has come from.
2. `alternate`: An alternative representation of the resource, may it be another metadata standard the data is available in or simply a human-readable version in HTML or PDF.
3. `about`: A resource that is related or further explains the resource, e.g. a user guide.
4. `canonical`: This relation type usually points to a publicly accessible and more long-lived URL for a resource that otherwise often requires (Bearer) authentication with a short-lived token.
This way the the exposed resources can be used by clients without additional authentication steps.
For example, a shared user-defined process or batch job results could be exposed via a canonical link.
If a URL should be publicly available to everyone, it can simply a user-specific URL, e.g. `https://geodatacube.example/processes/john_doe/ndvi`.
For resources that should only be accessible to a certain group of user, a signed URL could be given, e.g. `https://geodatacube.example/processes/81zjh1tc2pt52gbx/ndvi`.
Generally, it is RECOMMENDED to add descriptive titles (propertty `title`) and media type information (propertty `type`) for a better user experience.
## Error Handling
The success of requests MUST be indicated using [HTTP status codes](https://www.rfc-editor.org/rfc/rfc7231.html#section-6) according to [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html).
If the API responds with a status code between 100 and 399 the back-end indicates that the request has been handled successfully.
In general an error is communicated with a status code between 400 and 599. Client errors are defined as a client passing invalid data to the service and the service *correctly* rejecting that data. Examples include invalid credentials, incorrect parameters, unknown versions, or similar. These are generally "4xx" HTTP error codes and are the result of a client passing incorrect or invalid data. Client errors do *not* contribute to overall API availability.
Server errors are defined as the server failing to correctly return in response to a valid client request. These are generally "5xx" HTTP error codes. Server errors *do* contribute to the overall API availability. Calls that fail due to rate limiting or quota failures MUST NOT count as server errors.
### JSON error object
A JSON error object SHOULD be sent with all responses that have a status code between 400 and 599.
``` json
{
"id": "936DA01F-9ABD-4D9D-80C7-02AF85C822A8",
"code": "SampleError",
"message": "A sample error message.",
"url": "https://geodatacube.example/docs/errors/SampleError"
}
```
Sending `code` and `message` is REQUIRED.
* A back-end MAY add a free-form `id` (unique identifier) to the error response to be able to log and track errors with further non-disclosable details.
* The `code` is proprietary textual error code.
* The `message` explains the reason the server is rejecting the request. For "4xx" error codes the message explains how the client needs to modify the request.
By default the message MUST be sent in English language. Content Negotiation is used to localize the error messages: If an `Accept-Language` header is sent by the client and a translation is available, the message should be translated accordingly and the `Content-Language` header must be present in the response. See "[How to localize your API](http://apiux.com/2013/04/25/how-to-localize-your-api/)" for more information.
* `url` is an OPTIONAL attribute and contains a link to a resource that is explaining the error and potential solutions in-depth.
### Standardized status codes
The API usually uses the following HTTP status codes for successful requests:
- **200 OK**:
Indicates a successful request **with** a response body being sent.
- **201 Created**
Indicates a successful request that successfully created a new resource. Sends a `Location` header to the newly created resource **without** a response body.
- **202 Accepted**
Indicates a successful request that successfully queued the creation of a new resource, but it has not been created yet. The response is sent **without** a response body.
- **204 No Content**:
Indicates a successful request **without** a response body being sent.
The API has some commonly used HTTP status codes for failed requests:
- **400 Bad Request**:
The back-end responds with this error code whenever the error has its origin on client side and no other HTTP status code in the 400 range is suitable.
- **401 Unauthorized**:
The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.
- **403 Forbidden**:
The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource.
- **404 Not Found**:
The resource specified by the path does not exist, i.e. one of the resources belonging to the specified identifiers are not available at the back-end.
*Note:* Unsupported endpoints MAY also return HTTP status code 501.
- **500 Internal Server Error**:
The error has its origin on server side and no other status code in the 500 range is suitable.
- **501 Not Implemented**:
The requested endpoint is part of the API specification, but is not implemented (yet) by the back-end.
*Note:* Unsupported endpoints MAY also return HTTP status code 404.
If a HTTP status code in the 400 range is returned, the client SHOULD NOT repeat the request without modifications. For HTTP status code in the 500 range, the client MAY repeat the same request later.
All HTTP status codes defined in RFC 7231 in the 400 and 500 ranges can be used as error code in addition to the most used status codes mentioned here. Responding with error codes 400 and 500 SHOULD be avoided in favor of any more specific standardized or proprietary error code.
## Temporal data
Date, time, intervals and durations are formatted based on ISO 8601 or its profile [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar.
# Authentication
The API offers one forms of authentication by default:
* Basic at `GET /credentials/basic`
* OpenID Connect at `GET /credentials/oidc`
After authentication with any of the methods listed above, the tokens obtained during the authentication workflows can be sent to protected endpoints in subsequent requests.
Further authentication methods MAY be added by back-ends.
<SecurityDefinitions />
**Note:** Although it is possible to request several public endpoints for capabilities and discovery that don't require authorization, it is RECOMMENDED that clients (re-)request the public endpoints that support Bearer authentication with the Bearer token once available to also retrieve any private data that is made available specifically for the authenticated user.
This may require that clients clear any cached data they retrieved from public endpoints before.
# Cross-Origin Resource Sharing (CORS)
> Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources [...] on a web page to be requested from another domain outside the domain from which the first resource was served. [...]
> CORS defines a way in which a browser and server can interact to determine whether or not it is safe to allow the cross-origin request. It allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests.
Source: [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
Geodatacube-API-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can't access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. [CORS is a recommendation of the W3C organization](https://www.w3.org/TR/cors/). The following chapters will explain how back-end providers can implement CORS support.
**Tip**: Most servers can send the required headers and the responses to the OPTIONS requests automatically for all endpoints. Otherwise you may also use a proxy server to add the headers and OPTIONS responses.
## CORS headers
The following headers MUST be included with every response:
| Name | Description | Example |
| -------------------------------- | ------------------------------------------------------------ | ------- |
| Access-Control-Allow-Origin | Allowed origin for the request, including protocol, host and port or `*` for all origins. It is RECOMMENDED to return the value `*` to allow requests from browser-based implementations. | `*` |
| Access-Control-Expose-Headers | Some endpoints require to send additional HTTP response headers such as `GDC-Identifier` and `Location`. To make these headers available to browser-based clients, they MUST be white-listed with this CORS header. The following HTTP headers are white-listed by browsers and MUST NOT be included: `Cache-Control`, `Content-Language`, `Content-Length`, `Content-Type`, `Expires`, `Last-Modified` and `Pragma`. At least the following headers MUST be listed in this version of the API: `Link`, `Location`, and `GDC-Identifier`. | `Link, Location, GDC-Identifier` |
### Example request and response
Request:
```http
POST /api/v1/jobs HTTP/1.1
Host: geodatacube.example
Origin: https://company.example:8080
Authorization: Bearer basic//ZXhhbXBsZTpleGFtcGxl
```
Response:
```http
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, GDC-Identifier, Link
Content-Type: application/json
Location: https://geodatacube.example/api/v1/jobs/abc123
GDC-Identifier: abc123
```
## OPTIONS method
All endpoints must respond to the `OPTIONS` HTTP method. This is a response for the preflight requests made by web browsers before sending the actual request (e.g. `POST /jobs`). It needs to respond with a status code of `204` and no response body.
**In addition** to the HTTP headers shown in the table above, the following HTTP headers MUST be included with every response to an `OPTIONS` request:
| Name | Description | Example |
| -------------------------------- | ------------------------------------------------------------ | ------- |
| Access-Control-Allow-Headers | Comma-separated list of HTTP headers allowed to be sent with the actual (non-preflight) request. MUST contain at least `Authorization` if any kind of authorization is implemented by the back-end. | `Authorization, Content-Type` |
| Access-Control-Allow-Methods | Comma-separated list of HTTP methods allowed to be requested. Back-ends MUST list all implemented HTTP methods for the endpoint. | `OPTIONS, GET, POST, PATCH, PUT, DELETE` |
| Content-Type | SHOULD return the content type delivered by the request that the permission is requested for. | `application/json` |
### Example request and response
Request:
```http
OPTIONS /api/v1/jobs HTTP/1.1
Host: geodatacube.example
Origin: https://company.example:8080
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type
```
Note that the `Access-Control-Request-*` headers are automatically attached to the requests by the browsers.
Response:
```http
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: OPTIONS, GET, POST, PATCH, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Expose-Headers: Location, GDC-Identifier, Link
Content-Type: application/json
```
contact:
name: OGC Testbed 19
url: 'https://www.ogc.org/initiatives/t-19/'
email: info@ogc.org
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
- name: Capabilities
description: General information about the API implementation and other supported capabilities at the back-end.
- name: Account Management
description: |-
The following endpoints handle authentication and basic user profiles. See also [Authentication](#section/Authentication). In general, the API only defines a minimum subset of account management. It allows to [authenticate and authorize](http://www.differencebetween.net/technology/difference-between-authentication-and-authorization/) a user, which may include [user registration with OpenID Connect](http://openid.net/specs/openid-connect-registration-1_0.html),
For accounting, quota handling and similar functionality you can explore the openEO API.
Therefore, the API leaves some aspects open that have to be handled by the back-ends separately, including
* credentials recovery, e.g. retrieving a forgotten password
* user data management, e.g. changing the users payment details or email address
* payments, i.e. topping up credits for pre-paid services or paying for post-paid services
* accounting related tasks, e.g. processing costs and creating invoices,
* user registration (except for [user registration with OpenID Connect](http://openid.net/specs/openid-connect-registration-1_0.html)).
- name: Data Discovery / Access
description: |-
These endpoints allow to list the collections that are available at the back-end and can be used as data cubes for data processing. It builds on top of:
- OGC API - Coverages - Part 1
- STAC API (incl. STAC Data Cube extension)
- name: OGC API - Coverages
description: Data access through OGC API - Coverages - Part 1 (v0.0.2)
- name: OGC API - Features / STAC API
description: >-
**OPTIONAL.** Data access through OGC API - Features - Part 1 (v1.0.0) and STAC API (v1.0.0)
- name: Process Discovery
description: |-
**OPTIONAL.** These endpoints allow to list the predefined processes that are available at the back-end. To list user-defined processes see 'openEO - User-Defined Processes'.
- name: OGC API - Processes
description: >-
**OPTIONAL.** Data processing through OGC API - Processes - Part 1 (v1.0.0)
- name: openEO
description: >-
**OPTIONAL.** Data processing through openEO (v1.2.0)
- name: openEO - User-Defined Processes
description: >-
**OPTIONAL.** These endpoints allow to store and manage user-defined processes with their process graphs at the back-end.
- name: openEO - Secondary Services (OGC APIs)
description: >-
**OPTIONAL.** On-demand access to data using other web service protocols (e.g., OGC API - Tiles / Maps).
servers:
- url: 'https://geodatacube.example/api'
description: >-
The URL of the API MAY freely be chosen by the back-end providers.
Nevertheless, all servers MUST support HTTPS as the authentication methods
are not secure with HTTP only!
paths:
/:
get:
summary: Information about the back-end
operationId: capabilities
description: >-
Lists general information about the back-end, including which version
and endpoints of the geodatacube API are supported. May also include billing
information.
tags:
- Capabilities
security:
- {}
responses:
'200':
description: |-
Information about the API version and supported endpoints /
features.
This endpoint MUST always be available for the API to be valid.
content:
application/json:
schema:
title: Capabilities
type: object
required:
- id
- title
- description
- gdc_version
- endpoints
- links
properties:
gdc_version:
type: string
description: >-
Version number of the geodatacube API specification this back-end
implements.
enum:
- 1.0.0-beta
backend_version:
type: string
description: >-
Version number of the back-end implementation.
Every change on back-end side MUST cause a change of the
version number.
example: 1.1.2
stac_version:
$ref: '#/components/schemas/stac_version'
api_version:
type: string
description: >-
If the openEO API is implemented: Version number of the openEO API specification this back-end
implements.
example: 1.2.0
type:
type: string
enum:
- Catalog
description: >-
For STAC versions >= 1.0.0-rc.1 this field is required.
example: Catalog
id:
type: string
description: >-
Identifier for the service.
This field originates from STAC and is used as unique identifier for the STAC catalog available at `/collections`.
example: cool-eo-cloud
title:
type: string
description: The name of the service.
example: Example Cloud Corp.
description:
type: string
format: commonmark
description: >-
A description of the service, which allows the service
provider to introduce the user to its service.
[CommonMark 0.29](http://commonmark.org/) syntax MAY be
used for rich text representation.
example: |-
This service is provided to you by [Example Cloud Corp.](https://cloud.example). It implements the full geodatacube API and allows to process a range of 999 EO data sets, including
* Sentinel 1/2/3 and 5
* Landsat 7/8
A free plan is available to test the service. For further information please contact our customer service at [support@cloud.example](mailto:support@cloud.example).
conformsTo:
$ref: '#/components/schemas/conformsTo'
endpoints:
type: array
description: >-
Lists all supported endpoints. Supported are all
endpoints, which are implemented, return usually
a 2XX or 3XX HTTP status code and are fully compatible
to the API specification.
An entry for this endpoint (path `/` with method `GET`)
SHOULD NOT be listed.
Each path MUST only be listed once in the array.
items:
title: Endpoint
type: object
required:
- path
- methods
properties:
path:
description: >-
Path to the endpoint, relative to the URL of this
endpoint. In general the paths MUST follow the paths
specified in the openAPI specification as closely as
possible. Therefore, paths MUST be prepended with a
leading slash, but MUST NOT contain a trailing
slash. Variables in the paths MUST be placed in
curly braces and follow the parameter names in the
openAPI specification, e.g. `{job_id}`.
type: string
methods:
description: >-
Supported HTTP verbs in uppercase. It is OPTIONAL to
list `OPTIONS` as method (see the [CORS section](#section/Cross-Origin-Resource-Sharing-(CORS))).
type: array
items:
type: string
enum:
- GET
- POST
- PATCH
- PUT
- DELETE
- OPTIONS
example:
- path: /collections
methods:
- GET
- path: '/collections/{collection_id}'
methods:
- GET
- path: /processes
methods:
- GET
- path: /jobs
methods:
- GET
- POST
- path: '/jobs/{job_id}'
methods:
- GET
- DELETE
- PATCH
links:
description: |-
Links related to this service, e.g. the homepage of
the service provider or the terms of service.
1. `terms-of-service` (optional): A link to the terms of service. If
a back-end provides a link to the terms of service, the
clients MUST provide a way to read the terms of service
and only connect to the back-end after the user agreed to
them. The user interface MUST be designed in a way that
the terms of service are not agreed to by default, i.e.
the user MUST explicitly agree to them.
2. `privacy-policy` (optional): A link to the privacy policy (GDPR).
If a back-end provides a link to a privacy policy, the
clients MUST provide a way to read the privacy policy and
only connect to the back-end after the user agreed to
them. The user interface MUST be designed in a way that
the privacy policy is not agreed to by default, i.e. the
user MUST explicitly agree to them.
3. `service-desc` (required) and `service-doc` (optional):
A link to the API definition.
Use `service-desc` for machine-readable API definition and
`service-doc` for human-readable API definition.
4. `http://www.opengis.net/def/rel/ogc/1.0/conformance` (required):
A link to the Conformance declaration (see `/conformance`).
5. `data` (required): A link to the collections (see `/collections`).
6. `create-form` (optional): A link to a user registration page.
7. `recovery-form` (optional): A link to a page where a user can
recover a user account (e.g. to reset the password or send
a reminder about the username to the user's email account).
For additional relation types see also the lists of
[common relation types](#section/API-Principles/Web-Linking).
type: array
items:
$ref: '#/components/schemas/link'
example:
- href: 'https://cloud.example'
rel: about
type: text/html
title: Homepage of the service provider
- href: 'https://cloud.example/tos'
rel: terms-of-service
type: text/html
title: Terms of Service
- href: 'https://cloud.example/privacy'
rel: privacy-policy
type: text/html
title: Privacy Policy
- href: 'https://cloud.example/register'
rel: create-form
type: text/html
title: User Registration
- href: 'https://cloud.example/lost-password'
rel: recovery-form
type: text/html
title: Reset Password
- href: 'https://cloud.example/api/v1/conformance'
rel: http://www.opengis.net/def/rel/ogc/1.0/conformance
type: application/json
title: OGC Conformance Classes
- href: 'https://cloud.example/api/v1/openapi.json'
rel: service-desc
type: application/vnd.oai.openapi+json;version=3.0
title: OpenAPI 3.0 description of the API
- href: 'https://cloud.example/api/v1/collections'
rel: data
type: application/json
title: List of Datasets
4XX:
$ref: '#/components/responses/client_error'
5XX:
$ref: '#/components/responses/server_error'
/file_formats:
get:
summary: Supported file formats
operationId: list-file-types
description: |-
Lists supported input and output file formats.
*Input* file formats specify which file a back-end can *read* from.
*Output* file formats specify which file a back-end can *write* to.
The response to this request is an object listing all available input
and output file formats separately with their parameters and additional
data. This endpoint does not include the supported secondary web
services.
**Note**: Format names and parameters MUST be fully aligned with the
GDAL codes if available, see [GDAL Raster
Formats](https://gdal.org/drivers/raster/index.html) and [OGR Vector
Formats](https://gdal.org/drivers/vector/index.html). It is OPTIONAL to
support all output format parameters supported by GDAL. Some file
formats not available through GDAL may be defined centrally for the geodatacube.
Custom file formats or parameters MAY be defined.
The format descriptions must describe how the file formats relate to
data cubes. Input file formats must describe how the files have to be
structured to be transformed into data cubes. Output file formats must
describe how the data cubes are stored at the back-end and how the
resulting file structure looks like.
Back-ends MUST NOT support aliases, for example it is not allowed to
support `geotiff` instead of `gtiff`. Nevertheless, geodatacube clients MAY
translate user input input for convenience (e.g. translate `geotiff` to
`gtiff`). Also, for a better user experience the back-end can specify a
`title`.
Format names MUST be accepted in a *case insensitive* manner throughout the API.
tags:
- openEO
security:
- {}
- Bearer: []
responses:
'200':
description: >-
An object with containing all input and output format separately.
For each property `input` and `output` an object is defined where
the file format names are the property keys and the property values
are objects that define a title, supported parameters and related
links.
content:
application/json:
schema:
title: File Formats
type: object
required:
- input
- output
properties:
input:
title: Input File Formats
type: object
description: >-
Map of supported input file formats, i.e. file formats a
back-end can **read** from. The property keys are the file
format names that are used by clients and users, for
example in process graphs.
additionalProperties:
$ref: '#/components/schemas/file_format'
output:
title: Output File Formats
type: object
description: >-
Map of supported output file formats, i.e. file formats a
back-end can **write** to. The property keys are the file
format names that are used by clients and users, for
example in process graphs.
additionalProperties:
$ref: '#/components/schemas/file_format'
example:
output:
GTiff:
title: GeoTiff
description: Export to GeoTiff. Doesn't support cloud-optimized GeoTiffs (COGs) yet.
gis_data_types:
- raster
parameters:
tiled:
type: boolean
description: >-
This option can be used to force creation of tiled
TIFF files [true]. By default [false] stripped TIFF
files are created.
default: false
compress:
type: string
description: Set the compression to use.
default: NONE
enum:
- JPEG
- LZW
- DEFLATE
- NONE
jpeg_quality:
type: integer
description: Set the JPEG quality when using JPEG.
minimum: 1
maximum: 100
default: 75
links:
- href: 'https://gdal.org/drivers/raster/gtiff.html'
rel: about
title: GDAL on the GeoTiff file format and storage options
GPKG:
title: OGC GeoPackage
gis_data_types:
- raster
- vector
parameters:
version:
type: string
description: >-
Set GeoPackage version. In AUTO mode, this will be
equivalent to 1.2 starting with GDAL 2.3.
enum:
- auto
- '1'
- '1.1'
- '1.2'
default: auto
links:
- href: 'https://gdal.org/drivers/raster/gpkg.html'
rel: about
title: GDAL on GeoPackage for raster data
- href: 'https://gdal.org/drivers/vector/gpkg.html'
rel: about
title: GDAL on GeoPackage for vector data
input:
GPKG:
title: OGC GeoPackage
gis_data_types:
- raster
- vector
parameters:
table:
type: string
description: >-
**RASTER ONLY.** Name of the table containing the
tiles. If the GeoPackage dataset only contains one
table, this option is not necessary. Otherwise, it
is required.
links:
- href: 'https://gdal.org/drivers/raster/gpkg.html'
rel: about
title: GDAL on GeoPackage for raster data
- href: 'https://gdal.org/drivers/vector/gpkg.html'
rel: about
title: GDAL on GeoPackage for vector data
4XX:
$ref: '#/components/responses/client_error'
5XX:
$ref: '#/components/responses/server_error'
/conformance:
get:
summary: Conformance classes this API implements
operationId: conformance
description: |-
Lists all conformance classes specified in various standards that the
implementation conforms to. Conformance classes are commonly used in
all OGC APIs and the STAC API specification.
The conformance classes listed at this endpoint and listed in the
corresponding `conformsTo` property in `GET /` MUST be equal.
More details:
- [STAC API](https://github.com/radiantearth/stac-api-spec), especially the conformance class "STAC API - Collections"
- [OGC APIs](https://ogcapi.ogc.org/)
tags:
- Capabilities
responses:
'200':
description: The URIs of all conformance classes supported by the server.
content:
application/json:
schema:
title: OGC Conformance Classes
type: object
required:
- conformsTo
properties:
conformsTo:
$ref: '#/components/schemas/conformsTo'
5XX:
$ref: '#/components/responses/server_error'
/collections:
get:
summary: Basic metadata for all datasets
operationId: list-collections
description: |-
Lists available collections with at least the required information.
It is **strongly RECOMMENDED** to keep the response size small by
omitting larger optional values from the objects in `collections` (e.g. the
STAC `summaries` and `cube:dimensions` properties).
To get the full metadata for a collection clients MUST
request `GET /collections/{collection_id}`.
Note: Although it is possible to request public collections without
authorization, it is RECOMMENDED that clients (re-)request the collections
with the Bearer token once available to also retrieve any private collections.
**NOTE:** This endpoint may return collections from STAC API / openEO API and OGC API - Coverages.
Distinguish them via the `stac_version` property which is always present for STAC API / openEO API, but not for OGC API - Coverages.
tags:
- Data Discovery / Access
security:
- {}
- Bearer: []
parameters:
- $ref: '#/components/parameters/pagination_limit'
responses:
'200':
description: Lists of collections and related links.
content:
application/json:
schema:
title: Collections
type: object
required:
- collections
- links
properties:
collections:
type: array
items:
allOf:
- $ref: '#/components/schemas/collection'
anyOf:
- title: Coverage Collection
- $ref: '#/components/schemas/stac_collection'
links:
$ref: '#/components/schemas/links_pagination'
example:
collections:
- stac_version: 1.0.0
type: Collection
id: Sentinel-2A
title: Sentinel-2A MSI L1C
description: >-
Sentinel-2A is a wide-swath, high-resolution,
multi-spectral imaging mission supporting Copernicus
Land Monitoring studies, including the monitoring of
vegetation, soil and water cover, as well as observation
of inland waterways and coastal areas.
license: proprietary
extent:
spatial:
bbox:
- - -180
- -56
- 180
- 83
temporal:
interval:
- - '2015-06-23T00:00:00Z'
- '2019-01-01T00:00:00Z'
keywords:
- copernicus
- esa
- msi
- sentinel
providers:
- name: European Space Agency (ESA)
roles:
- producer
- licensor
url: >-
https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi
- name: Google Earth Engine
roles:
- host
url: >-
https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2
links:
- rel: license
href: >-
https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf
- stac_version: 1.0.0
type: Collection
id: MOD09Q1
title: >-
MODIS/Terra Surface Reflectance 8-Day L3 Global 250m SIN
Grid V006
description: >-
The MOD09Q1 Version 6 product provides an estimate of
the surface spectral reflectance of Terra MODIS Bands
1-2 corrected for atmospheric conditions such as gasses,
aerosols, and Rayleigh scattering. Provided along with
the two 250 m MODIS bands is one additional layer, the
Surface Reflectance QC 250 m band. For each pixel, a
value is selected from all the acquisitions within the
8-day composite period. The criteria for the pixel
choice include cloud and solar zenith. When several
acquisitions meet the criteria the pixel with the
minimum channel 3 (blue) value is used. Validation at
stage 3 has been achieved for all MODIS Surface
Reflectance products.
license: proprietary
extent:
spatial:
bbox:
- - -180
- -90
- 180
- 90
temporal:
interval:
- - '2000-02-01T00:00:00Z'
- null
links:
- rel: license
href: 'https://geodatacube.example/api/v1/collections/MOD09Q1/license'
links:
- rel: alternate
href: 'https://geodatacube.example/csw'
title: OGC Catalogue Services 3.0
4XX:
$ref: '#/components/responses/client_error_auth'
5XX:
$ref: '#/components/responses/server_error'
'/collections/{collection_id}':
get:
summary: Full metadata for a specific dataset
operationId: describe-collection
description: |-
Lists **all** information about a specific collection specified by the
identifier `collection_id`.
Note: Providing the Bearer token is REQUIRED for private collections.
**NOTE:** This endpoint may return collections from STAC API / openEO API and OGC API - Coverages.
Distinguish them via the `stac_version` property which is always present for STAC API / openEO API, but not for OGC API - Coverages.
tags:
- Data Discovery / Access
security:
- {}
- Bearer: []
parameters:
- $ref: '#/components/parameters/collection_id'
responses:
'200':
description: JSON object with the full collection metadata.
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/collection'
anyOf:
- title: Coverage Collection
- required:
- 'cube:dimensions'
- summaries
allOf:
- $ref: '#/components/schemas/stac_collection'
example:
stac_version: 1.0.0
stac_extensions:
- https://stac-extensions.github.io/datacube/v2.2.0/schema.json
type: Collection
id: Sentinel-2
title: Sentinel-2 MSI L2A
description: >-
Sentinel-2A is a wide-swath, high-resolution, multi-spectral
imaging mission supporting Copernicus Land Monitoring
studies.
license: proprietary
keywords:
- copernicus
- esa
- msi
- sentinel
providers:
- name: European Space Agency (ESA)
roles:
- producer
- licensor
url: >-
https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi
- name: Google
roles:
- host
url: >-
https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2
extent:
spatial:
bbox:
- - -180
- -56
- 180
- 83
temporal:
interval:
- - '2015-06-23T00:00:00Z'
- null
links:
- rel: license
href: https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf
type: application/pdf
- rel: http://www.opengis.net/def/rel/ogc/1.0/queryables
href: https://geodatacube.example/api/v1/collections/Sentinel-2A/queryables
type: application/schema+json
- rel: about
href: https://earth.esa.int/web/sentinel/user-guides/sentinel-2-msi/product-types/level-1c
type: text/html
title: ESA Sentinel-2 MSI Level-1C User Guide
- rel: example
href: 'https://geodatacube.example/api/v1/collections/Sentinel-2/examples/true-color.json'
type: application/json
title: Example Process for True-Color Visualization
- rel: example
href: 'https://geodatacube.example/api/v1/collections/Sentinel-2/examples/ndvi.json'
type: application/json
title: Example Process for NDVI Calculation and Visualization
'cube:dimensions':
x:
type: spatial
axis: x
extent:
- -180
- 180
reference_system: 4326
y:
type: spatial
axis: 'y'
extent:
- -56
- 83
reference_system: 4326
t:
type: temporal
extent:
- '2015-06-23T00:00:00Z'
- null
step: null
bands:
type: bands
values:
- B1
- B2
- B3
- B4
- B5
- B6
- B7
- B8
- B8A
- B9
- B10
- B11
- B12
summaries:
'constellation':
- Sentinel-2
'platform':
- Sentinel-2A
- Sentinel-2B
'instruments':
- MSI
'eo:cloud_cover':
minimum: 0
maximum: 75
'sat:orbit_state':
- ascending
- descending
'gsd':
- 10
- 20
- 60
'eo:bands':
- name: B1