forked from nasa/harmony
-
Notifications
You must be signed in to change notification settings - Fork 0
/
service-callbacks-v0.1.0.yml
252 lines (232 loc) · 11.9 KB
/
service-callbacks-v0.1.0.yml
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
openapi: 3.0.3
info:
title: Callback API for Harmony backend services
description: Describes the parameters necessary to call back to Harmony and their constraints
version: 0.1.0
contact:
name: Harmony API Support
url: https://bugs.earthdata.nasa.gov/browse/HARMONY
email: [email protected] # Avoid email. For best response, reach out in Slack or file a JIRA issue
x-eosdis-slack-channel: '#harmony'
servers:
- url: /{callback-id}
description: Harmony callback root
variables:
callback-id:
default: no-default-uuid
description: An opaque callback ID provided by the Harmony message
tags:
- name: Response
description: Response callback
paths:
/response:
post:
tags:
- Response
summary: The primary (only) callback endpoint
description: All communication from backend service to Harmony is sent on this endpoint, including
indciation of errors, partial results, full results, and progress
operationId: response
parameters:
# Common parameters between sync and async requests
- name: error
in: query
description:
Valid in both synchronous and asynchronous service requests.
Passing this parameter indicates that an error has occurred in performing the service with a
user-facing message as the value of the parameter. Internal error diagnostics should be logged
to STDOUT or STDERR. The logger provided by the Harmony Python library will provide a common
format if used.
Once a service calls back with this parameter, no further callbacks will be accepted.
For synchronous requests, Harmony returns the message to the user in an appropriate format for
the request with an HTTP 400 response. For asynchronous requests, Harmony marks the request
as failed and places the error message in a user-accessible field. Harmony maintains user access
to any prior partial results sent by the service as well as the progress percentage of the request
example:
- error=
required: false
style: form
explode: false
schema:
type: string
# Parameters for responding to synchronous requests
- name: redirect
description:
Valid in synchronous service requests only. Deprecated support for asynchronous requests.
Indicates that the service request has completed successfully and the user can retrieve the response
at the URL value of this parameter. The URL can either be an HTTPS URL or a URL to an S3 staging
location to a bucket and key where Harmony has permission to sign GetObject requests. If it is an
HTTPS URL, Harmony will redirect the user to its location. If it is an S3 staging location, Harmony
will pre-sign a URL that can be used for a subsequent GetObject request. Staged S3 objects should
have the correct "Content-Type" tag set. The Harmony Python library does this automatically when using
the "completed_with_redirect" helper method. Harmony provides services with a preferred staging prefix
with each request of the form "s3://<staging-bucket>/public/<org-name>/<service-name>/<uuid>/", which
services should use whenever possible to maintain appropriate ACLs and user-facing utilities.
Harmony prefers to use S3 locations as it can cache subsequent requests and control retention.
example:
- redirect=s3://example-staging-bucket/public/my-daac/my-service/11111111-2222-3333-4444-555555555555/output.tif
- redirect=https://my-daac.example.com//output.tif
in: query
required: false
style: form
explode: false
schema:
type: string
format: uri
# Parameters for responding to asynchronous requests
- name: status
description:
Valid for asynchronous service requests only. Ignored for synchronous requests.
Updates the status of the request. Harmony maintains all status transitions up to "successful", which is
the only value services should provide here. status=successful indicates the service request completed.
Once Harmony receives this final status, it de-registers the service callback and any subsequent attempts
to call back will fail.
example:
- status=successful
in: query
required: false
style: form
explode: false
schema:
type: string
enum: [ successful ]
- name: progress
description:
Valid for asynchronous service requests only. Ignored for synchronous requests.
Indicates an approximate percentage progress through the overall request, as a percentage. Harmony
automatically starts this value at 0 and sets it to 100 for a successful response. Services should
only use this parameter to provide intermediate feedback to users.
in: query
required: false
style: form
explode: false
schema:
type: integer
minimum: 0
maximum: 100
- name: item
description:
Valid for asynchronous service requests only. Ignored for synchronous requests.
Provides a single output for an asynchronous service call. Depending on the call and service, this may
be the only output or one of several. See the example for syntax on providing this as a query parameter.
Services must provide, at a minimum, the href, type, bbox, and temporal properties for each item. This
list of required fields is likely to be expanded at a future date to include additinal provenance tracking
and metadata. As we add more required fields, they will be marked required here but Harmony will provide
graceful degradation for services not yet upgraded. For example, Harmony allows services to not provide
bbox or temporal fields, but this is deprecated behavior and will result in outputs from those services not
producing STAC catalogs.
example:
- item[href]=s3://some-location/myfile.nc&item[type]='application/x-netcdf4'&item[temporal]=2020-01-01T00:00:00Z,2020-01-01T00:00:00Z&item[bbox]=-100,-70,100,70
in: query
required: false
style: deepObject
explode: true
schema:
type: object
properties:
href:
type: string
description:
A URL where the data can be located. This URL can either be an HTTPS URL or a URL to an S3 staging
location to a bucket and key where Harmony has permission to sign GetObject requests. If it is an
HTTPS URL, Harmony will redirect the user to its location. If it is an S3 staging location, Harmony
will pre-sign a URL that can be used for a subsequent GetObject request. Staged S3 objects should
have the correct "Content-Type" tag set. The Harmony Python library does this automatically when using
the "completed_with_redirect" helper method. Harmony provides services with a preferred staging prefix
with each request of the form "s3://<staging-bucket>/public/<org-name>/<service-name>/<uuid>/", which
services should use whenever possible to maintain appropriate ACLs and user-facing utilities.
Harmony prefers to use S3 locations as it can cache subsequent requests and control retention.
format: uri
type:
type: string
description:
The media type of the data contained at the href property's URL
format: media-type
example:
- image/tiff;subtype=geotiff
- application/x-netcdf4
- application/x-zarr
title:
type: string
description:
A short human-readable name indicating the contents of the file. Optional. Consider setting this to
the basename of the file, as is the default when using the Harmony Python library.
temporal:
type: string
description:
Two RFC-3339 date/time strings (with optional fractional seconds) separated by a comma indicating the start and
end time of the data in the result item. Harmony provides a "temporal" field with each input granule in the input
message which has "start" and "end" fields containing an RFC-3339 date/time for the granule temporal range to aid
in producing this output.
example:
- 2020-01-01T00:00:00.000Z,2020-01-02T12:00:00.000Z
bbox:
type: string
description:
Four comma-separated numbers corresponding to the [West, South, East, North] minimum bounding rectangle of the resulting
file. Harmony provides a "bbox" field with each input granule in the input message for aid in producing the output.
Set the East coordinate lower than the West coordinate to indicate a bounding box that crosses the antimeridian.
required:
- href
- type
- temporal
- bbox
requestBody:
description:
Valid in synchronous service requests only.
Contains bytes to be streamed directly to the user as a result of the service output. This marks the request complete and
deregisters its callback, causing any further callbacks to produce an error. Services should set appropriate "Content-Type"
and "Content-Length" headers according to the file contents.
required: false
content:
default:
schema:
description: The data bytes to be streamed to the user, verbatim, as a result of the service call.
responses:
"200":
description: links to the API capabilities
content:
application/json:
schema:
type: string
description: The string literal "Ok". Indicates the callback was processed successfully
"400":
description:
Indicates that the request was incorrect, for example due to a parameter being out of the acceptable
range or an invalid combination of parameters being provided. The message field in the response provides
additional details
content:
application/json:
schema:
$ref: '#/components/schemas/error'
"404":
description:
Indicates that there is no callback available at the given URL. If Harmony provided the URL in the first
place, the most likely cause of this is that you have already called back in a way that indicates your
service has completed, either with an error, a callback, or a status=complete parameter
content:
application/json:
schema:
$ref: '#/components/schemas/error'
"500":
description:
Indicates an unexpected error in accepting the response. Contact the Harmony team or file a bug to help
resolve it.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
components:
schemas:
error:
required:
- code
- message
type: object
properties:
code:
type: integer
description: The error code (400)
message:
type: string
description: The error message