-
Notifications
You must be signed in to change notification settings - Fork 12
/
openapi.yaml
358 lines (339 loc) · 14.2 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
openapi: 3.0.2
info:
title: openEO Commercial Data API extension
version: 0.1.0
description: >-
The Commercial Data API extension provides an interface for discovering,
ordering and using commercial data in the openEO API.
contact:
name: openEO Consortium
url: 'https://openeo.org'
email: [email protected]
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
externalDocs:
url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/federation/README.md
tags:
- name: Orders
description: Management of commercial data orders
servers:
- url: 'https://openeo.example/api/{version}'
description: >-
The URL of the API MAY freely be chosen by the back-end providers. The
path, including API versioning, is a *recommendation* only. Nevertheless,
all servers MUST support HTTPS as the authentication methods are not
secure with HTTP only!
variables:
version:
default: v1
description: >-
API versioning is RECOMMENDED. As the openEO API is following
[SemVer](https://semver.org/) only the MAJOR part of the stable
version numbers (i.e. versions >= 1.0.0) SHOULD be used for API
versioning in the URL. The reason is that backward-incompatible
changes are usually introduced by major changes. Therefore, the
version number in the URL MUST not be used by the clients to detect
the version number of the API. Use the version number returned from
`GET /` instead.
paths:
/orders:
get:
summary: List all commercial data orders
operationId: list-orders
description: |-
Lists all created orders submitted by a user, regardless of the status
or the collection.
It is **strongly RECOMMENDED** to keep the response size small by
omitting all optional non-scalar values from objects in `orders` (e.g. `parameters`).
To get the full metadata for an order clients MUST request `GET /orders/{order_id}`.
tags:
- Orders
security:
- Bearer: []
parameters:
- $ref: '../../openapi.yaml#/components/parameters/pagination_limit'
responses:
'200':
description: List of orders and related links.
content:
application/json:
schema:
title: Orders
type: object
required:
- orders
- links
properties:
orders:
type: array
items:
$ref: '#/components/schemas/order'
links:
$ref: '../../openapi.yaml#/components/schemas/links_pagination'
4XX:
$ref: '../../openapi.yaml#/components/responses/client_error_auth'
5XX:
$ref: '../../openapi.yaml#/components/responses/server_error'
post:
summary: Create a new order
operationId: create-order
description: |-
Create an order for selected items (products).
When an order is created through through this endpoint, the data isn't yet ordered from the commercial data provider. The client MUST explicitly confirm the order through `POST /orders/{order_id}` whereupon the order is executed.
The order can contain additional parameters that specify how the items should be delivered.
For example, it might be possible to set the projection, resampling method, bit depth etc. of the delivered data.
Backends SHOULD expose the available ordering parameters in `GET /collections/{collection_id}` in the `order_parameters` field, following the `process_parameters` schema of [`GET /service_types`](https://openeo.org/documentation/1.0/developers/api/reference.html#tag/Secondary-Services/operation/list-service-types).
Returns `Location` and `OpenEO-Identifier` header with the link to the detailed information about the order.
tags:
- Orders
security:
- Bearer: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- source_collection_id
- items
- parameters
properties:
source_collection_id:
type: string
description: Unique identifier of the collection.
items:
type: array
description: Array of items IDs to order.
items:
$ref: '#/components/schemas/order_id'
parameters:
$ref: '#/components/schemas/order_parameters'
responses:
'201':
description: The order has been created successfully.
headers:
Location:
required: true
schema:
description: |-
Absolute URL to the newly created order.
The URL points to the metadata endpoint
`GET /orders/{order_id}` with the `{order_id}` being the
unique identifier (ID) of the created order.
format: uri
type: string
example: 'https://openeo.example/api/v1/orders/40264b5-c3ae-46f4-a907-0f612d763d97'
OpenEO-Identifier:
required: true
schema:
$ref: '#/components/schemas/order_id'
4XX:
$ref: '../../openapi.yaml#/components/responses/client_error_auth'
5XX:
$ref: '../../openapi.yaml#/components/responses/server_error'
'/orders/{order_id}':
parameters:
- $ref: '#/components/parameters/order_id'
get:
summary: Full metadata for an order
operationId: describe-order
description: |-
Get full metadata of the order.
Backends can optionally link to the spatial and temporal extent information and other metadata about the items using the relation type `item`, preferrably by implementing and linking to `GET /collections/{collection_id}/items/{item_id}`.
tags:
- Orders
security:
- Bearer: []
responses:
'200':
description: Full order information.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/order'
- type: object
required:
- items
4XX:
$ref: '../../openapi.yaml#/components/responses/client_error_auth'
5XX:
$ref: '../../openapi.yaml#/components/responses/server_error'
post:
summary: Confirm an order
operationId: confirm-order
description: |-
Confirm the order, execute the purchase and ingest the data into a target collection.
When an order is created through `POST /order`, the data isn't yet ordered from the commercial data provider. The client MUST explicitly confirm the order whereupon the order is executed, the costs are deducted from the client's account and the data is ingested in the target collection.
The target collection is the collection through which the ordered data is made available. The source and the target collection can be the same or different, it's up to the backend if the ordered data id ingested into a new target collection or the existing source collection. Additionally, if the backend creates new target collections, it can provide access to the union of all purchased products through the source collection.
This endpoint only has an effect if `order:status` is `orderable`.
If the user doesn't have sufficient funds, the endpoint should return an error and `order:status` should not change.
Otherwise, the `order:status` changes from `orderable` to `ordered` until a new order status (e.g. `succeeded` or `failed`) becomes available.
tags:
- Orders
security:
- Bearer: []
responses:
'202':
description: The order has been confirmed successfully.
4XX:
$ref: '../../openapi.yaml#/components/responses/client_error_auth'
5XX:
$ref: '../../openapi.yaml#/components/responses/server_error'
delete:
summary: Delete an order
operationId: delete-order
description: |-
Removes the order and all ordered items from the back-ends.
If an order is still in progress, it cancels the order.
Costs MAY still occur.
tags:
- Orders
security:
- Bearer: []
responses:
'204':
description: The order and data has been successfully deleted.
4XX:
$ref: '../../openapi.yaml#/components/responses/client_error_auth'
5XX:
$ref: '../../openapi.yaml#/components/responses/server_error'
components:
schemas:
order_id:
type: string
description: >-
Unique identifier of the order at the back-end, which MUST match the specified pattern.
pattern: '^[\w\-\.~]+$'
example: fb6799ab
item_id:
type: string
description: >-
Unique identifier of the item. Must be unique within a collection.
example: c8a1f88d-89cf-4933-9118-45e9c1a5df20
order_parameters:
type: object
description: >-
Key-value pairs of available `order_parameters` as listed at
`GET /collections/{collection_id}` for filtering available items.
additionalProperties:
x-additionalPropertiesName: Order Parameter Name
description: Value of the order parameter for the request.
example:
resamplingKernel: 'NN'
order:
type: object
title: Order
description: >-
Information about an order.
The properties with the `order:` prefix follow the fields defined in the
[STAC Order Extension](https://github.com/stac-extensions/order/tree/v1.0.0).
required:
- id
- order:status
- order:date
- source_collection_id
- target_collection_id
- costs
properties:
id:
$ref: '#/components/schemas/order_id'
order:id:
type: string
description: >-
Identifier of the order at the data provider.
example: 40264b5-c3ae-46f4-a907-0f612d763d97
order:status:
type: string
description: |-
The status of the order.
* `orderable`: The item or asset is orderable via the provider scenario.
* `ordered`: The item or asset is ordered and the provider is preparing to make it available.
* `pending`: The item or asset is ordered but wait for an activation before being able for shipping.
* `shipping` The item or asset order are being processed by the provider to provide you with the asset(s).
* `succeeded`: The provider has delivered your order and asset(s) are available.
* `failed`: The provider is not able to deliver the order.
* `canceled` The order has been canceled.
enum:
- orderable
- ordered
- pending
- shipping
- succeeded
- failed
- canceled
order:date:
type: string
format: date-time
description: The order time. Formatted as a
[RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time.
example: '2017-01-01T09:32:12Z'
order:expiration_date:
type: string
format: date-time
description: The validity time of the order. Formatted as a
[RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time.
example: '2999-01-01T00:00:00Z'
source_collection_id:
type: string
description: Unique identifier of the source collection.
pattern: '^[\w\-\.~\/]+$'
example: 'PLEIADES'
target_collection_id:
type: string
description: >-
Unique identifier of the target collection.
Can be the same as `source_collection_id`.
pattern: '^[\w\-\.~\/]+$'
example: 'PLEIADES'
costs:
$ref: '../../openapi.yaml#/components/schemas/money'
parameters:
$ref: '#/components/schemas/order_parameters'
items:
type: array
description: List of ordered item IDs.
items:
$ref: '#/components/schemas/item_id'
links:
type: array
description: |-
Links related to this order, e.g. to metadata for ordered items
listed in `items`.
It is highly RECOMMENDED to provide links with the
following `rel` (relation) types:
1. `item`: A link back to a valid STAC Item that has been ordered.
Could be a link to `GET /collections/{collection_id}/items/{item_id}`.
2. `order`: A link pointing to a dcoument describing the ordering
terms and conditions of the data provider.
For additional relation types see also the lists of
[common relation types in openEO](#section/API-Principles/Web-Linking).
items:
$ref: '../../openapi.yaml#/components/schemas/link'
parameters:
order_id:
name: order_id
in: path
description: >-
Unique identifier of an order.
This corresponds to the `id` property of an order.
required: true
schema:
$ref: '#/components/schemas/order_id'
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: >-
The Bearer Token MUST consist of the authentication method, a provider
ID (if available) and the token itself. All separated by a forward slash
`/`. Examples (replace `TOKEN` with the actual access token): (1) Basic
authentication (no provider ID available): `basic//TOKEN` (2) OpenID
Connect (provider ID is `ms`): `oidc/ms/TOKEN`. For OpenID Connect, the
provider ID corresponds to the value specified for `id` for each
provider in `GET /credentials/oidc`.
Basic:
type: http
scheme: basic