SOL002SOL003_resp.yaml 20.2 KB
Newer Older
1 2 3
# Copyright (c) ETSI 2017.
# https://forge.etsi.org/etsi-forge-copyright-notice.txt

4
responses:
5
  206:
6
    description: >
7
      206 PARTIAL CONTENT
8
    headers:
9 10 11 12 13 14 15 16 17
      Content-Type:
        description: >
          The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
      Content-Range:
        description: >
          The Content-Range response HTTP header indicates where in a full body message a partial message belongs.
18
        type: string
19 20
        maximum: 1
        minimum: 1
21 22 23 24 25 26 27 28
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
29
      Version:
30 31
        description: >
          Version of the API used in the response.
32 33 34
        type: string
        maximum: 1
        minimum: 1
35 36
    schema:
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"
37

38
  303:
39 40 41 42
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
43 44 45 46 47 48 49 50 51 52
        maximum: 1
        minimum: 1
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
53
      Version:
54 55
        description: >
          Version of the API used in the response.
56 57 58
        type: string
        maximum: 1
        minimum: 1
59

60 61
  400:
    description: >
62 63 64 65 66 67 68 69 70 71 72 73 74
      400 BAD REQUEST

      400 code can be returned in the following specified cases, the specific cause has to be proper specified in the
      "ProblemDetails" structure to be returned.

      If the request is malformed or syntactically incorrect (e.g. if the request URI contains incorrect
      query parameters or the payload body contains a syntactically incorrect data structure),
      the API producer shall respond with this response code. The "ProblemDetails" structure shall be provided,
      and should include in the "detail" attribute more information about the source of the problem.

      If the response to a GET request which queries a container resource would be so big that the performance
      of the API producer is adversely affected, and the API producer does not support paging for the affected resource,
      it shall respond with this response code. The "ProblemDetails" structure shall be provided, and should include
bernini's avatar
bernini committed
75
      in the "detail" attribute more information about the source of the problem.
76 77 78 79 80 81 82 83 84 85 86 87

      If there is an application error related to the client's input that cannot be easily mapped to any other
      HTTP response code ("catch all error"), the API producer shall respond with this response code.
      The "ProblemDetails" structure shall be provided, and shall include in the "detail" attribute more information
      about the source of the problem.

      If the request contains a malformed access token, the API producer should respond with this response.
      The details of the error shall be returned in the WWW Authenticate HTTP header, as defined in IETF RFC 6750
      and IETF RFC 7235. The ProblemDetails structure may be provided.

      The use of this HTTP error response code described above is applicable to the use of the OAuth 2.0
      for the authorization of API requests and notifications, as defined in clauses 4.5.3.3 and 4.5.3.4.
88 89 90 91 92 93 94 95 96 97 98 99 100 101
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
102
      Version:
103 104
        description: >
          Version of the API used in the response.
105 106 107
        type: string
        maximum: 1
        minimum: 1
108
    schema:
109 110 111
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

  401:
112
    description: >
113 114 115 116 117 118
      401 UNAUTHORIZED

      If the request contains no access token even though one is required, or if the request contains an authorization
      token that is invalid (e.g. expired or revoked), the API producer should respond with this response.
      The details of the error shall be returned in the WWW-Authenticate HTTP header, as defined in IETF RFC 6750
      and IETF RFC 7235. The ProblemDetails structure may be provided.
119 120 121 122 123 124 125 126 127 128 129 130
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
131 132
        maximum: 1
        minimum: 0
133
      Version:
134 135
        description: >
          Version of the API used in the response.
136 137 138
        type: string
        maximum: 1
        minimum: 1
139
    schema:
140 141 142
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

  403:
143
    description: >
144 145 146 147 148 149
      403 FORBIDDEN

      If the API consumer is not allowed to perform a particular request to a particular resource,
      the API producer shall respond with this response code. The "ProblemDetails" structure shall be provided.
      It should include in the "detail" attribute information about the source of the problem,
      and may indicate how to solve it.
150 151 152 153 154 155 156 157 158 159 160 161 162 163
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
164
      Version:
165 166
        description: >
          Version of the API used in the response.
167 168 169
        type: string
        maximum: 1
        minimum: 1
170
    schema:
171 172 173
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

  404:
174
    description: >
175 176 177 178 179 180 181 182 183 184 185
      404 NOT FOUND

      If the API producer did not find a current representation for the resource addressed by the URI passed
      in the request or is not willing to disclose that one exists, it shall respond with this response code.
      The "ProblemDetails" structure may be provided, including in the "detail" attribute information about
      the source of the problem, e.g. a wrong resource URI variable.

      This response code is not appropriate in case the resource addressed by the URI is a container resource
      which is designed to contain child resources, but does not contain any child resource at the time
      the request is received. For a GET request to an existing empty container resource, a typical response
      contains a 200 OK response code and a payload body with an empty array.
186 187 188 189 190 191 192 193 194 195 196 197 198 199
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
200
      Version:
201 202
        description: >
          Version of the API used in the response.
203 204 205
        type: string
        maximum: 1
        minimum: 1
206
    schema:
207 208 209
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

  405:
210
    description: >
211
      405 METHOD NOT ALLOWED
212

213 214
      If a particular HTTP method is not supported for a particular resource, the API producer shall respond
      with this response code. The "ProblemDetails" structure may be omitted.
215 216 217 218 219 220
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
221 222 223 224 225
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
226 227
        type: string
        maximum: 1
228
        minimum: 0
229
      Version:
230 231
        description: >
          Version of the API used in the response.
232 233 234
        type: string
        maximum: 1
        minimum: 1
235
    schema:
236 237 238
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

  406:
239
    description: >
240 241 242 243 244
      406 NOT ACCEPTABLE

      If the "Accept" header does not contain at least one name of a content type that is acceptable
      to the API producer, the API producer shall respond with this response code.
      The "ProblemDetails" structure may be omitted.
245 246 247
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
248 249
        type: string
        maximum: 1
250
        minimum: 1
251 252 253 254 255
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
256 257
        type: string
        maximum: 1
258
        minimum: 0
259
      Version:
260 261
        description: >
          Version of the API used in the response.
262 263 264
        type: string
        maximum: 1
        minimum: 1
265
    schema:
266 267 268
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

  409:
269 270 271 272 273 274
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
275 276 277 278 279
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
280 281
        type: string
        maximum: 1
282
        minimum: 0
283
      Version:
284 285
        description: >
          Version of the API used in the response.
286 287 288
        type: string
        maximum: 1
        minimum: 1
289 290
    schema:
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"
291

292
  412:
293
    description: >
294
      412 PRECONDITION FAILED
295

296 297 298 299
      Error: A precondition given in an HTTP request header is not fulfilled.
      Typically, this is due to an ETag mismatch, indicating that the resource was modified by another entity.
      The response body should contain a ProblemDetails structure, in which the "detail" attribute should convey
      more information about the error.
300 301 302 303 304 305
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
306 307 308 309 310
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
311 312
        type: string
        maximum: 1
313
        minimum: 0
314
      Version:
315 316
        description: >
          Version of the API used in the response.
317 318 319
        type: string
        maximum: 1
        minimum: 1
320
    schema:
321 322
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

bernini's avatar
bernini committed
323 324
  413:
    description: >
325
      413 PAYLOAD TOO LARGE
bernini's avatar
bernini committed
326

327 328 329
      If the payload body of a request is larger than the amount of data the API producer is willing or able to process,
      it shall respond with this response code, following the provisions in IETF RFC 7231 for the use
      of the "Retry-After" HTTP header and for closing the connection. The "ProblemDetails" structure may be omitted.
bernini's avatar
bernini committed
330 331 332 333 334 335
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
336 337 338 339 340 341 342 343
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
344
      Version:
345 346
        description: >
          Version of the API used in the response.
347 348 349
        type: string
        maximum: 1
        minimum: 1
bernini's avatar
bernini committed
350
    schema:
351 352
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

bernini's avatar
bernini committed
353 354
  414:
    description: >
355
      414 URI TOO LONG
bernini's avatar
bernini committed
356

357 358 359
      If the request URI of a request is longer than the API producer is willing or able to process,
      it shall respond with this response code. This condition can e.g. be caused by passing long queries
      in the request URI of a GET request. The "ProblemDetails" structure may be omitted.
bernini's avatar
bernini committed
360 361 362 363 364 365
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
366 367 368 369 370 371 372 373
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
374
      Version:
375 376
        description: >
          Version of the API used in the response.
377 378 379
        type: string
        maximum: 1
        minimum: 1
bernini's avatar
bernini committed
380
    schema:
381
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"
bernini's avatar
bernini committed
382

383 384
  416:
    description: >
385
      416 RANGE NOT SATISFIABLE
386 387 388 389 390 391
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
392 393 394 395 396 397 398 399
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
400
      Version:
401 402
        description: >
          Version of the API used in the response.
403 404 405
        type: string
        maximum: 1
        minimum: 1
406
    schema:
407 408
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

409 410
  422:
    description: >
411 412 413 414 415 416 417 418
      422 UNPROCESSABLE ENTITY

      If the payload body of a request contains syntactically correct data (e.g. well-formed JSON) but the data
      cannot be processed (e.g. because it fails validation against a schema), the API producer shall respond
      with this response code. The "ProblemDetails" structure shall be provided, and should include in the "detail"
      attribute more information about the source of the problem.

      This error response code is only applicable for methods that have a request body.
419 420 421 422 423 424
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
425 426 427 428 429 430 431 432
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
433
      Version:
434 435
        description: >
          Version of the API used in the response.
436 437 438
        type: string
        maximum: 1
        minimum: 1
439
    schema:
440 441
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

bernini's avatar
bernini committed
442 443
  429:
    description: >
444 445 446 447 448 449
      429 TOO MANY REQUESTS

      If the API consumer has sent too many requests in a defined period of time and the API producer is able
      to detect that condition ("rate limiting"), the API producer shall respond with this response code,
      following the provisions in IETF RFC 6585 [17] for the use of the "Retry-After" HTTP header.
      The "ProblemDetails" structure shall be provided and shall include in the "detail" attribute more information
bernini's avatar
bernini committed
450
      about the source of the problem.
451 452 453

      The period of time and allowed number of requests are configured within the API producer by means
      outside the scope of the present document.
bernini's avatar
bernini committed
454 455 456 457 458 459
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
460 461 462 463 464 465 466 467
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
468
      Version:
469 470
        description: >
          Version of the API used in the response.
471 472 473
        type: string
        maximum: 1
        minimum: 1
bernini's avatar
bernini committed
474
    schema:
475
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"
bernini's avatar
bernini committed
476

477 478
  500:
    description: >
479 480 481 482 483 484
      500 INTERNAL SERVER ERROR

      If there is an application error not related to the client's input that cannot be easily mapped to any other
      HTTP response code ("catch all error"), the API producer shall respond with this response code.
      The "ProblemDetails" structure shall be provided, and shall include in the "detail" attribute more information
      about the source of the problem.
485 486 487 488 489 490
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
491 492 493 494 495 496 497 498
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
499
      Version:
500 501
        description: >
          Version of the API used in the response.
502 503 504
        type: string
        maximum: 1
        minimum: 1
505
    schema:
506 507
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

508 509
  503:
    description: >
510
      503 SERVICE UNAVAILABLE
511

512 513 514 515
      If the API producer encounters an internal overload situation of itself or of a system it relies on,
      it should respond with this response code, following the provisions in IETF RFC 7231 for the use of
      the "Retry-After" HTTP header and for the alternative to refuse the connection. The "ProblemDetails"
      structure may be omitted.
516 517 518 519 520 521
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
522 523 524 525 526 527 528 529
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
530
      Version:
531 532
        description: >
          Version of the API used in the response.
533 534 535
        type: string
        maximum: 1
        minimum: 1
536
    schema:
537 538
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

bernini's avatar
bernini committed
539 540
  504:
    description: >
541
      504 GATEWAY TIMEOUT
bernini's avatar
bernini committed
542

543 544 545
      If the API producer encounters a timeout while waiting for a response from an upstream server
      (i.e. a server that the API producer communicates with when fulfilling a request), it should respond
      with this response code.
bernini's avatar
bernini committed
546 547 548 549 550 551
    headers:
      Content-Type:
        description: The MIME type of the body of the response.
        type: string
        maximum: 1
        minimum: 1
552 553 554 555 556 557 558 559
      WWW-Authenticate:
        description: >
          Challenge if the corresponding HTTP request has not provided
          authorization, or error details if the corresponding HTTP
          request has provided an invalid authorization token.
        type: string
        maximum: 1
        minimum: 0
560
      Version:
561 562
        description: >
          Version of the API used in the response.
563 564 565
        type: string
        maximum: 1
        minimum: 1
bernini's avatar
bernini committed
566
    schema:
567
      $ref: "../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"