Skip to content

Commit

Permalink
Correct documentation around the productData endpoint and sinceDateTi…
Browse files Browse the repository at this point in the history 
…me (#132)

* Correct documentation around the productData endpoint and sinceDateTime parameter.

* Changes to keep in line with OpenAPI spec changes in #132

Co-authored-by: Barrie Cooper <[email protected]>
  • Loading branch information
@rockydevnet @barrie-cooper
rockydevnet and barrie-cooper authored Feb 24, 2022
1 parent cab1f02 commit ca03d61
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 41 deletions.
6 changes: 3 additions & 3 deletions UKHO.ExchangeSetService.API/UKHO.ExchangeSetService.API/Controllers/ProductDataController.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@ public virtual Task<IActionResult> PostProductDataByProductVersions([FromBody] L
/// Provide all the releasable data after a datetime.
/// </summary>
/// <remarks>Given a datetime, build an Exchange Set of all the releasable ENC versions that have been issued since that datetime.</remarks>
/// <param name="sinceDateTime" example="Wed, 21 Oct 2015 07:28:00 GMT" >The date and time from which changes are requested. Any changes since the date will be returned. The value should be the Last-Modified date returned by the last request to this operation. The date is in RFC 1123 format. The date and time must be within 28 days and cannot be in future.
/// <param name="sinceDateTime" example="Wed, 21 Oct 2015 07:28:00 GMT" >The date and time from which changes are requested. Any changes since the date will be returned. The value should be the value in the `Date` header returned by the last request to this operation. The date is in RFC 1123 format. The date and time must be within 28 days and cannot be in future.
/// <br/><para><i>Example</i> : Wed, 21 Oct 2015 07:28:00 GMT</para>
/// </param>
/// <param name="callbackUri">An optional callback URI that will be used to notify the requestor once the requested Exchange Set is ready to download from the File Share Service. If not specified, then no call back notification will be sent.</param>
Expand All @@ -215,9 +215,9 @@ public virtual Task<IActionResult> PostProductDataByProductVersions([FromBody] L
[Route("/productData")]
[Consumes("application/json")]
[Produces("application/json")]
[SwaggerResponseHeader(statusCode: (int)HttpStatusCode.OK, name: "Last-Modified", type: "string", description: "Returns the date and time the file was last modified. The date format is in RFC 1123 format.")]
[SwaggerResponseHeader(statusCode: (int)HttpStatusCode.OK, name: "Date", type: "string", description: "Returns the current date and time on the server and should be used in subsequent requests to the productData operation to ensure that there are no gaps due to minor time difference between your own and UKHO systems. The date format is in RFC 1123 format.")]
[SwaggerResponse(statusCode: (int)HttpStatusCode.OK, type: typeof(ExchangeSetResponse), description: "<p>A JSON body that indicates the URL that the Exchange Set will be available on as well as the number of cells in that Exchange Set.</p><p>If there are no updates since the sinceDateTime parameter, then a 'Not modified' response will be returned.</p>")]
[SwaggerResponseHeader(statusCode: (int)HttpStatusCode.NotModified, name: "Last-Modified", type: "string", description: "Returns the date and time the file was last modified. The date format is in RFC 1123 format.")]
[SwaggerResponseHeader(statusCode: (int)HttpStatusCode.NotModified, name: "Date", type: "string", description: "Returns the current date and time on the server and should be used in subsequent requests to the productData operation to ensure that there are no gaps due to minor time difference between your own and UKHO systems. The date format is in RFC 1123 format.")]
[SwaggerResponse(statusCode: (int)HttpStatusCode.BadRequest, type: typeof(ErrorDescription), description: "Bad request.")]
[SwaggerResponseHeader(statusCode: (int)HttpStatusCode.TooManyRequests, name: "Retry-After", type: "integer", description: "Specifies the time you should wait in seconds before retrying.")]
[SwaggerResponse(statusCode: (int)HttpStatusCode.InternalServerError, type: typeof(InternalServerError), description: "Internal Server Error.")]
Expand Down
79 changes: 41 additions & 38 deletions exchangeSetService_OpenApi_definition.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,6 @@ paths:
responses:
"200":
description: A JSON body that indicates the URL that the Exchange Set will be available on as well as the number of cells in that Exchange Set.
headers:
Last-Modified:
schema:
$ref: "#/components/schemas/Last-Modified"
content:
application/json:
schema:
Expand All @@ -81,11 +77,11 @@ paths:

"500":
$ref: "#/components/responses/internalServerError"

callbacks:
fulfilmentResponse:
$ref: "#/components/callbacks/fulfilmentResponse"

/productData/productVersions:
post:
summary: Given a set of ENC versions (e.g. Edition x Update y) provide any later releasable files.
Expand Down Expand Up @@ -143,10 +139,10 @@ paths:

"500":
$ref: "#/components/responses/internalServerError"

callbacks:
fulfilmentResponse:
$ref: "#/components/callbacks/fulfilmentResponse"
$ref: "#/components/callbacks/fulfilmentResponse"

/productData:
post:
Expand All @@ -167,9 +163,10 @@ paths:
If there are no updates since the sinceDateTime parameter, then a 'Not modified' response will be returned.
headers:
Last-Modified:
Date:
description: Returns the current date and time on the server and should be used in subsequent requests this operation to ensure that there are no gaps due to minor time difference between your own and UKHO systems. The date format is in RFC 1123 format.
schema:
$ref: "#/components/schemas/Last-Modified"
$ref: "#/components/schemas/Date-Header"
content:
application/json:
schema:
Expand All @@ -178,9 +175,9 @@ paths:
"304":
description: Not modified.
headers:
Last-Modified:
Date:
schema:
$ref: "#/components/schemas/Last-Modified"
$ref: "#/components/schemas/Date-Header"

"400":
description: Bad request.
Expand All @@ -200,7 +197,7 @@ paths:

"500":
$ref: "#/components/responses/internalServerError"

callbacks:
fulfilmentResponse:
$ref: "#/components/callbacks/fulfilmentResponse"
Expand All @@ -212,17 +209,17 @@ paths:
description: |
Returns a token direct from AAD using Client Credentials
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
description: The application ID that's assigned to the distributor's app. This will be provided to the distributor when they register their application.
client_secret:
type: string
description: The client secret that has been generated for the distributor's app when the app was registered. The client secret must be URL-encoded before being sent.
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
description: The application ID that's assigned to the distributor's app. This will be provided to the distributor when they register their application.
client_secret:
type: string
description: The client secret that has been generated for the distributor's app when the app was registered. The client secret must be URL-encoded before being sent.
responses:
200:
description: OK.
Expand All @@ -232,13 +229,13 @@ paths:
type: object
properties:
token_type:
type: string
type: string
expires_in:
type: string
type: string
ext_expires_in:
type: string
type: string
access_token:
type: string
type: string
example: |
{
"token_type": "Bearer",
Expand All @@ -256,11 +253,11 @@ paths:
{
"correlationId": "184ef711-b039-4c24-b81a-89081d8f324c",
"errors": [
{
"source": "request",
"description": "request missing client_id and/or client_secret"
}
]
{
"source": "request",
"description": "request missing client_id and/or client_secret"
}
]
}
401:
$ref: "#/components/responses/unauthorised"
Expand All @@ -281,7 +278,7 @@ components:
name: sinceDateTime
required: true
description: |
The date and time from which changes are requested. Any changes since the date will be returned. The value should be the Last-Modified date returned by the last request to this operation. The date is in RFC 1123 format. The date and time must be within 28 days and cannot be in future.
The date and time from which changes are requested. Any changes since the date will be returned. The value should be the value in the `Date` header returned by the last request to this operation. The date is in RFC 1123 format. The date and time must be within 28 days and cannot be in future.
schema:
type: string
format: date-time
Expand Down Expand Up @@ -443,6 +440,12 @@ components:
description: Returns the date and time the file was last modified. The date format is in RFC 1123 format.
example: Wed, 21 Oct 2015 07:28:00 GMT

Date-Header:
type: string
format: date-time
description: Returns the current date and time on the server and should be used in subsequent requests to the productData operation to ensure that there are no gaps due to minor time difference between your own and UKHO systems. The date format is in RFC 1123 format.
example: Wed, 21 Oct 2015 07:28:00 GMT

####################################
# Error Response Objects #
####################################
Expand Down Expand Up @@ -623,19 +626,19 @@ components:
######################
# callbacks #
######################

callbacks:
fulfilmentResponse:
'{$request.query.callbackUri}':
post:
summary: Notify the Exchange Set requestor that this is now ready to download on the File Share Service.
description: |
Once the Exchange Set has been committed on File Share Service, a notification will be sent to the callbackURI (if specified).
## Data:
The data for the notification will follow the CloudEvents 1.0 standard, with the data portion containing the same Exchange Set data as the response to the original API request.
requestBody:
content:
application/json:
Expand Down

0 comments on commit ca03d61

Please sign in to comment.