From 7d396c921af8a0c133a3b5f563ac340e3ff1e57b Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 17 Oct 2023 13:47:38 +0100 Subject: [PATCH 1/9] Remove all dimension, observation and metadata endpoints and models Also remove import_tasks which are a CMD specific feature --- swagger.yaml | 1257 +------------------------------------------------- 1 file changed, 8 insertions(+), 1249 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 25639f53..d85487b9 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -1,4 +1,5 @@ swagger: "2.0" +host: ons.gov.uk info: description: "Used to find information about data published by the ONS. `Datasets` are published in unique `versions`, which are categorized by `edition`. @@ -6,6 +7,7 @@ info: of dimension `options` in a version can be used to retrieve `observation` level data." version: "1.0.0" title: "Explore our data" + contact: me license: name: "Open Government Licence v3.0" url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" @@ -22,32 +24,6 @@ parameters: description: "A unique id for a dataset to filter on" in: query type: string - dimension: - name: dimension - description: "A dimension from a dataset" - in: path - required: true - type: string - dimension_options: - description: "The name of the dimension option and a single value; each option (dimension) and corresponding value (code) must exist against the version - e.g. `age=30` or one of the dimension options can be represented by a wildcard value `*` e.g. `geography=*`" - name: "" - in: query - required: true - type: string - patch_options: - required: true - name: patch - schema: - $ref: '#/definitions/PatchOptions' - description: "A list of patch operations for a dimension option" - in: body - patch_dimensions: - required: true - name: patch - schema: - $ref: '#/definitions/PatchDimensions' - description: "A list of patch operations for a dimension" - in: body edition: name: edition description: "An edition of a dataset" @@ -66,18 +42,6 @@ parameters: in: path required: true type: string - import_tasks: - name: import_tasks - description: "A request body to update the state of an import task" - in: body - schema: - $ref: '#/definitions/ImportTasks' - inserted_observations: - name: inserted_observations - description: "A value to increment the inserted_observations within an instance" - in: path - required: true - type: integer instance_id: name: instance_id description: "A unique id for an instance" @@ -117,12 +81,6 @@ parameters: required: true schema: $ref: '#/definitions/Version' - node_id: - name: node_id - description: "An unique node id" - in: path - required: true - type: string newInstance: name: instance description: "An instance related to an import job" @@ -130,12 +88,6 @@ parameters: required: true schema: $ref: '#/definitions/NewInstance' - option: - name: option - description: "A option to set within a type" - in: path - required: true - type: string state: name: "state" description: "A comma separated list of state values to filter on (e.g. ‘completed,edition-confirmed’)" @@ -148,19 +100,6 @@ parameters: required: true schema: $ref: "#/definitions/Dataset" - update_dimension: - name: dimension - description: "A dimension object to update for a given instance" - in: body - required: true - schema: - $ref: '#/definitions/UpdateInstanceDimension' - update_dimension_option_request: - name: dimension_option - description: "A dimension option from an instance" - in: body - schema: - $ref: '#/definitions/UpdateDimensionOptionRequest' version: name: version description: "A version of a dataset" @@ -204,12 +143,6 @@ parameters: description: "A population type to search on to return datasets that are associated with that population type e.g. Usual-Residents. This is applicable to Census 2021 datasets only." in: query type: string - metadata_update: - name: metadata_update - in: body - required: true - schema: - $ref: "#/definitions/MetadataUpdate" securityDefinitions: FlorenceAPIKey: name: florence-token @@ -475,152 +408,6 @@ paths: description: "No version was found for an edition of a dataset using the id, edition and version provided" 500: $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}/versions/{version}/dimensions: - get: - tags: - - "Public" - summary: "Get a list of dimensions from a dataset" - description: "Get all dimensions which are used in the dataset" - parameters: - - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' - - $ref: '#/parameters/version' - - $ref: '#/parameters/limit' - - $ref: '#/parameters/offset' - responses: - 200: - description: "A json list of dimensions" - schema: - $ref: '#/definitions/Dimensions' - 400: - description: | - Invalid request, reasons can be one of the following: - * dataset id was incorrect - * edition was incorrect - * version was incorrect - 404: - description: "No dimensions found for version of an edition of a dataset using the id, edition and version provided" - 500: - $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}/versions/{version}/dimensions/{dimension}/options: - get: - tags: - - "Public" - summary: "Get a list of options from a dimension" - description: "Get a list of options which appear in this dimension and dataset. By default all options are returned, but a subset can be requested by providing offset and limit query parameters, or by providing the list of option IDs, only the IDs that are found will be returned." - parameters: - - $ref: '#/parameters/dimension' - - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' - - $ref: '#/parameters/version' - - $ref: '#/parameters/limit' - - $ref: '#/parameters/offset' - - $ref: '#/parameters/ids' - responses: - 200: - description: "Json object containing all options for a dimension" - schema: - $ref: '#/definitions/DimensionOptions' - 400: - description: | - Invalid request, reasons can be one of the following: - * dataset id was incorrect - * edition was incorrect - * version was incorrect - * dimension was incorrect - * query parameters incorrect offset provided - * query parameters incorrect limit provided - 404: - description: "No dimension options were found for dimension" - 500: - $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}/versions/{version}/metadata: - get: - tags: - - "Public" - summary: "Get metadata for a version" - description: "Get all metadata relevant to a version" - parameters: - - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' - - $ref: '#/parameters/version' - responses: - 200: - description: "Json object containing all metadata for a version" - schema: - $ref: '#/definitions/Metadata' - 400: - description: | - Invalid request, reasons can be one of the following: - * dataset id was incorrect - * edition was incorrect - 404: - description: "Version not found" - 500: - $ref: '#/responses/InternalError' - put: - tags: - - "Private" - summary: "Update metadata for a dataset and a version" - description: "Update metadata for a dataset and a version. The editable metadata can be updated only if both the dataset and the version have a state of associated" - parameters: - - $ref: '#/parameters/id' - - $ref: '#/parameters/edition' - - $ref: '#/parameters/version' - - $ref: '#/parameters/if_match' - - $ref: '#/parameters/metadata_update' - responses: - 200: - description: "The editable metadata has been updated" - 400: - description: | - Invalid request, reasons can be one of the following: - * invalid request body - * version was incorrect - 401: - description: "Unauthorised to update metadata" - 403: - description: "Unable to update resource, expected resource to have a state of associated" - 404: - description: "Version was not found for a dataset using the id and edition provided" - 409: - description: "Instance does not match the expected eTag" - 500: - $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}/versions/{version}/observations: - get: - tags: - - "Public" - summary: "Get specific observations" - description: "Get observations from a version of the dataset. By providing - a single option for each dimension, a single observation will be returned. - A wildcard (*) can be provided for one dimension, to retrieve a list of - observations." - parameters: - - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' - - $ref: '#/parameters/version' - - $ref: '#/parameters/dimension_options' - responses: - 200: - description: "Json object containing all metadata for a version" - schema: - $ref: '#/definitions/ObservationsEndpoint' - 400: - description: | - Invalid request, reasons can be one of the following: - * query parameters missing expected dimensions - * query parameters contain incorrect dimensions - * too many query parameters are set to wildcard (*) value; only one query parameter can be equal to * - 404: - description: | - Resource not found, reasons can be one of the following: - * dataset id was incorrect - * edition was incorrect - * version was incorrect - * observations not found for selected query paramaters - 500: - $ref: '#/responses/InternalError' /instances: get: tags: @@ -738,176 +525,6 @@ paths: $ref: '#/responses/ConflictError' 500: $ref: '#/responses/InternalError' - /instances/{instance_id}/dimensions: - get: - tags: - - "Private user" - summary: "Get a list of dimensions for an instance" - description: "Get all dimensions from an instance" - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/if_match' - produces: - - "application/json" - security: - - InternalAPIKey: [] - responses: - 200: - description: "Return a list of dimensions" - schema: - type: array - items: - $ref: '#/definitions/DimensionOption' - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 403: - $ref: '#/responses/ForbiddenError' - 404: - $ref: '#/responses/InstanceNotFound' - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - post: - deprecated: true - tags: - - "Private" - summary: "Create a dimension" - description: "Create a new dimension which is related to an instance" - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/update_dimension_option_request' - - $ref: '#/parameters/if_match' - security: - - InternalAPIKey: [] - responses: - 201: - description: "Dimension was created" - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 404: - $ref: '#/responses/InstanceNotFound' - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - patch: - tags: - - "Private" - summary: "Create one or more dimensions" - description: "Create one or more dimensions which are related to an instance" - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/patch_dimensions' - - $ref: '#/parameters/if_match' - produces: - - "application/json-patch+json" - security: - - InternalAPIKey: [] - responses: - 200: - description: "All dimensions were successfully created" - schema: - $ref: '#/definitions/PatchDimensions' - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 404: - $ref: '#/responses/InstanceNotFound' - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - - /instances/{instance_id}/dimensions/{dimension}: - put: - tags: - - "Private user" - summary: "Update dimension" - description: "Update the label and/or description of a dimension within an instance, by providing dimension name and properties to over write" - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/dimension' - - $ref: '#/parameters/update_dimension' - - $ref: '#/parameters/if_match' - security: - - InternalAPIKey: [] - responses: - 200: - description: "The instance has been updated" - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 403: - $ref: '#/responses/ForbiddenError' - 404: - $ref: '#/responses/InstanceNotFound' - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - /instances/{instance_id}/dimensions/{dimension}/options: - get: - tags: - - "Private user" - summary: "Get a list of options for a dimension" - description: "Get all unique options from a dimension" - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/dimension' - - $ref: '#/parameters/if_match' - produces: - - "application/json" - security: - - InternalAPIKey: [] - responses: - 200: - description: "Return a list of unique options" - schema: - type: object - properties: - dimension: - description: "The name of the dimension" - type: string - options: - description: "A list of all unique options within a dimension" - type: array - items: - type: string - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 403: - $ref: '#/responses/ForbiddenError' - 404: - description: "dimension does not match any dimensions within the instance" - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' /instances/{instance_id}/events: post: tags: @@ -940,139 +557,6 @@ paths: $ref: '#/responses/ConflictError' 500: $ref: '#/responses/InternalError' - /instances/{instance_id}/inserted_observations/{inserted_observations}: - put: - tags: - - "Private" - summary: "Increment the inserted observation count" - description: "This will add to the number already store in the api" - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/inserted_observations' - - $ref: '#/parameters/if_match' - security: - - InternalAPIKey: [] - responses: - 200: - description: "Added value to inserted observation" - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 404: - description: "InstanceId does not match any instances" - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - /instances/{instance_id}/import_tasks: - put: - tags: - - "Private" - summary: "Update import tasks for an instance" - description: "The instance import process involves multiple tasks. This endpoint updates the state of an import task." - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/import_tasks' - - $ref: '#/parameters/if_match' - security: - - InternalAPIKey: [] - responses: - 200: - description: "Updated the state of the import task" - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 404: - description: "InstanceId does not match any instances" - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - /instances/{instance_id}/dimensions/{dimension}/options/{option}: - patch: - tags: - - "Private" - summary: "Modify a dimension option for an instance" - description: | - Modify a dimension option for an instance by setting values for node_id or order - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/dimension' - - $ref: '#/parameters/option' - - $ref: '#/parameters/patch_options' - - $ref: '#/parameters/if_match' - produces: - - "application/json-patch+json" - security: - - InternalAPIKey: [] - responses: - 200: - description: "The dimension option was modified and the successfully applied patch operations are returned" - schema: - $ref: '#/definitions/PatchOptions' - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 403: - $ref: '#/responses/ForbiddenError' - 404: - description: "InstanceId does not match any instances" - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' - /instances/{instance_id}/dimensions/{dimension}/options/{option}/node_id/{node_id}: - put: - deprecated: true - tags: - - "Private" - summary: "Update a dimension with the node_id" - description: | - Update the dimension with a nodeId - parameters: - - $ref: '#/parameters/instance_id' - - $ref: '#/parameters/dimension' - - $ref: '#/parameters/node_id' - - $ref: '#/parameters/option' - - $ref: '#/parameters/if_match' - produces: - - "application/json" - security: - - InternalAPIKey: [] - responses: - 200: - description: "Updated the dimension with the nodeId" - headers: - ETag: - type: string - description: "Defines a unique instance resource version" - 400: - $ref: '#/responses/InvalidRequestError' - 401: - $ref: '#/responses/UnauthorisedError' - 403: - $ref: '#/responses/ForbiddenError' - 404: - description: "InstanceId does not match any instances" - 409: - $ref: '#/responses/ConflictError' - 500: - $ref: '#/responses/InternalError' responses: ConflictError: description: "Failed to process the request due to a conflict" @@ -1107,24 +591,6 @@ definitions: description: "The type of alert" example: "correction" type: string - Codelist: - type: object - properties: - href: - description: "A link to the codelist corresponding to this dimension" - type: string - id: - description: "The codelist id corresponding to this dimension" - type: string - name: - description: "The dimension name" - type: string - description: - description: "The dimension description" - type: string - label: - description: "A human readable label for dimension" - type: string CollectionID: description: "The id of the unpublished collection (of datasets) that this dataset is associated with" type: string @@ -1318,8 +784,6 @@ definitions: uri: description: "The uri to the location of this resource on the web" type: string - - Type: description: "The type for a dataset" type: string @@ -1337,190 +801,6 @@ definitions: description: "The type of the dataset" type: string example: "cantabular_table" - Dimension: - description: "A single dimension within a dataset" - type: object - properties: - description: - description: "" - type: string - dimension: - description: "The name of the dimension" - type: string - href: - description: "A link to the code-list entry for the dimension" - type: string - id: - description: "The id of the dimension" - type: string - is_area_type: - description: "Indicates if a dimension is an area-type (census datasets only)" - type: boolean - label: - description: "" - type: string - links: - type: object - properties: - code_list: - description: "The code list related to this dimension" - type: object - properties: - href: - description: "A URL to the code list" - type: string - id: - description: "The unique id for the code list" - type: string - options: - $ref: '#/definitions/OptionsLink' - version: - $ref: '#/definitions/VersionLink' - number_of_options: - description: "The number of options available for this dimension" - type: integer - variable: - description: "The variable name (census datasets only)" - type: string - Dimensions: - type: object - properties: - count: - description: "The number of dimensions returned for a version from an edition of a dataset" - readOnly: true - type: integer - items: - description: "An array of dimensions" - type: array - items: - $ref: '#/definitions/Dimension' - limit: - description: "The number of dimensions requested for a version from an edition of a dataset" - type: integer - offset: - description: "The first row of dimension for a version from an edition of a dataset to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of dimensions against a version from an edition of a dataset" - readOnly: true - type: integer - DimensionOptions: - type: object - properties: - count: - description: "The number of dimensions returned for a version from an edition of a dataset" - readOnly: true - type: integer - items: - description: "An array of dimension options" - type: array - items: - $ref: '#/definitions/DimensionOption' - limit: - description: "The number of dimensions requested for a version from an edition of a dataset" - type: integer - offset: - description: "The first row of dimension for a version from an edition of a dataset to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of dimensions against a version from an edition of a dataset" - readOnly: true - type: integer - DimensionOption: - type: object - properties: - dimension: - description: "The name of the dimension" - type: string - instance_id: - description: "The unique identifier for the instance in which this dimension option is associated to" - type: string - label: - description: "A label given to a dimension option" - type: string - links: - description: "A object with all resources related to a dimension option" - type: object - properties: - code: - description: "A link to the code of the dimension for this option" - type: object - properties: - href: - description: "The url of the code that refers to the dimension for this option" - type: string - id: - description: "The id of the code that refers to the dimension for this option" - type: string - code_list: - description: "A link to the code list the dimension for this option belongs to" - type: object - properties: - href: - description: "The url of the code list that the dimension for this option belongs to" - type: string - id: - description: "The id of the code list that the dimension for this option belongs to" - type: string - version: - description: "A link to the version of the dataset the option belongs to" - readOnly: true - type: object - properties: - href: - description: "The href of the version that this option belongs to" - type: string - id: - description: "The id of the version that this option belongs to" - type: string - node_id: - description: "The id of the node" - type: string - option: - description: "An option for a dimension" - type: string - PatchOptions: - description: "A list of operations to patch a dimension option. Can only handle adding values for /node_id and /order. Each element in the array is processed in sequential order." - type: array - items: - type: object - description: "Item containing all necessary information to make a single operation on the resource." - properties: - op: - description: | - The operation to be made on path. - * add - Sets the value for the provided path - type: string - enum: [add] - path: - description: "Path to value that needs to be operated on." - type: string - example: "/node_id" - enum: [/node_id, /order] - value: - description: "A value that will be set for the provided path. /node_id accepts string values, and /order accepts integer values." - example: "node_123" - PatchDimensions: - description: "A list of operations to patch dimensions. Can only handle adding lists of dimension values, and modifying order and node_id values for existing dimension options. The patch operations are executed in bulk to improve performance, and they are idempotent. If at least one of the provided dimensions and/or options in a patch path cannot be matched against existing dimension options, the request will fail with 404." - type: array - items: - type: object - description: "Item containing all necessary information to make a single operation on the resource." - properties: - op: - description: | - The operation to be made on path. - * add - Sets the value for the provided path - type: string - enum: ["add"] - path: - description: "Path to value that needs to be operated on." - type: string - example: "/-" - enum: ["/-", "/{dimension}/options/{option}/order", "/{dimension}/options/{option}/node_id"] - value: - description: "A list of dimenions that will be added to the instance." - example: "[{\"dimension\": \"dim1\", \"option\": \"op1\"}, {\"dimension\": \"dim1\", \"option\": \"op2\"}, {\"op\": \"add\", \"path\": \"/dim1/options/op1/order\", \"value\": 3}, {\"op\": \"add\", \"path\": \"/dim1/options/op2/node_id\", \"value\": \"node123\"}]" DownloadObject: description: "Object containing information of a downloadable file" type: object @@ -1586,43 +866,6 @@ definitions: * Info - for an information event * Error - for an error event type: string - ImportTasks: - type: object - properties: - build_hierarchies: - type: array - items: - type: object - properties: - code_list_id: - description: "The ID of the codelist that this hierarchy represents" - type: string - dimension_name: - description: "The name of the dimension the hierarchy represents" - type: string - state: - description: "The state of the import observations task" - type: string - build_search_indexes: - type: array - items: - type: object - properties: - dimension_name: - description: "The name of the dimension the search index represents" - type: string - state: - description: "The state of the import observations task" - type: string - import_observations: - type: object - properties: - state: - description: "The state of the import observations task" - type: string - total_inserted_observations: - description: "The number of inserted observations in this instance" - type: integer Instance: type: object properties: @@ -1638,11 +881,6 @@ definitions: type: string collection_id: $ref: '#/definitions/CollectionID' - dimensions: - description: "A list of codelists for each dimension of this instance" - type: array - items: - $ref: '#/definitions/Codelist' downloads: description: "A selection of download objects containing information of downloadable files." type: object @@ -1665,8 +903,6 @@ definitions: type: array items: type: string - import_tasks: - $ref: '#/definitions/ImportTasks' last_updated: description: "The last time an event happened" readOnly: true @@ -1687,15 +923,6 @@ definitions: description: "The ID of the dataset associated with this instance" example: "95c4669b-3ae9-4ba7-b690-87e890a1c67c" type: string - dimensions: - description: "An object describing the URL for the dimensions which are associated with this instance" - readOnly: true - type: object - properties: - href: - description: "The URL for a list of dimensions associated with this instance" - example: "http://localhost:22000/datasets/95c4669b-3ae9-4ba7-b690-87e890a1c67c/editions/2017/versions/1/dimensions" - type: string edition: description: "An object describing the ID and URL for the dataset edition that is associated with this instance" readOnly: true @@ -1800,166 +1027,13 @@ definitions: description: "The type of change" type: string example: "summary of changes" - Metadata: - description: "An object containing all metadata information against a version" + NewDatasetResponse: + description: "A model for the response body when creating a new dataset" type: object properties: - alerts: - description: "A list of alerts, for example corrections after the resource has been published" - type: array - items: - $ref: '#/definitions/Alert' - canonical_topic: - description: "The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the website taxonomy." - type: string - contacts: - description: "A list containing contact details of staticians for a dataset" - type: array - items: - $ref: '#/definitions/Contact' - description: - description: "A description for a dataset" - type: string - dimensions: - description: "A list of codelists for each dimension of this version" - type: array - items: - $ref: '#/definitions/Dimension' - distribution: - description: "A list of media types that the version data of an edition of a dataset can be accessed" - type: array - items: - type: string - downloads: - description: "A selection of download objects containing information of downloadable files." - type: object - properties: - csv: - $ref: '#/definitions/DownloadObject' - csvw: - $ref: '#/definitions/DownloadObject' - txt: - $ref: '#/definitions/DownloadObject' - xls: - $ref: '#/definitions/DownloadObject' - headers: - description: "A list of headers for a census dataset" - type: array - items: - type: "string" - keywords: - description: "A list of keywords for a dataset" - type: array - items: - type: "string" - latest_changes: - description: "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition" - type: array - items: - $ref: '#/definitions/LatestChange' - license: - description: "The standard Government license right text for the dataset" - type: string - dataset_links: - $ref: '#/definitions/MetadataLinks' - methodologies: - description: "A list of methodologies for a dataset" - type: array - items: - type: object - properties: - description: - description: "The description of a methodology" - type: string - href: - description: "The url to a methodology" - type: string - title: - description: "The title of a methodology" - type: string - national_statistic: - description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" - type: boolean - next_release: - description: "The next release date for a dataset" - type: string - publications: - description: "A list of publications for a dataset" - type: array - items: - type: object - properties: - description: - description: "The description of a publication" - type: string - href: - description: "The url to a publication" - type: string - title: - description: "The title of a publication" - type: string - publisher: - $ref: '#/definitions/Publisher' - qmi: - description: "Object containing information on the quality and methodology index of a dataset" - type: object - properties: - description: - description: "The description of a quality and methodology index" - type: string - href: - description: "The url to a quality and methodology index" - type: string - title: - description: "The title of a quality and methodology index" - type: string - related_datasets: - description: "A list of objects containing information of datasets related to a dataset" - type: array - items: - type: object - properties: - href: - description: "The url to a related dataset" - type: string - title: - description: "The title of a related dataset" - type: string - release_date: - description: "The release date of this version of the dataset" - type: string - release_frequency: - description: "The release frequency of a dataset" - type: string - subtopics: - description: "A list of subtopic ids that the dataset relates to within the website taxonomy." - type: array - items: - type: "string" - temporal: - $ref: '#/definitions/Temporal' - theme: - description: "The theme for a dataset" - type: string - title: - description: "The title of the dataset" - example: "CPI" - type: string - unit_of_measure: - description: "The unit of measure for the dataset observations" - type: string - uri: - description: "The uri to the location of the dataset on the web" - type: string - usage_notes: - $ref: '#/definitions/UsageNotes' - NewDatasetResponse: - description: "A model for the response body when creating a new dataset" - type: object - properties: - id: - description: "An unique id for a dataset" - example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" + id: + description: "An unique id for a dataset" + example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" type: string current: allOf: @@ -1983,17 +1057,10 @@ definitions: description: "A model for the request and response body for creating a new instance" type: object properties: - dimensions: - description: "A list of codelists for each dimension of this instance" - type: array - items: - $ref: '#/definitions/Codelist' id: description: "A unique id for an instance" readOnly: true type: string - import_tasks: - $ref: '#/definitions/ImportTasks' links: type: object properties: @@ -2047,84 +1114,6 @@ definitions: description: "An unique id for a dataset" example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91CD" - $ref: "#/definitions/Version" - ObservationsEndpoint: - description: "An object containing information on a list of observations for a given version of a dataset" - type: object - properties: - dimensions: - description: "A list of dimensions for the given query" - type: object - properties: - : - description: "Each field is a dimension () and will represent a query parameter in the request unless the query parameter is equal to a wildcard value (*)" - type: object - properties: - option: - description: "A list of links to the corresponding dimension codes for the given `dimension_options`" - type: object - properties: - href: - description: "A link to the corresponding dimension code for the given `dimension_option`" - type: string - example: "http://localhost:8080/codelists/AB12CD34/codes/K02000001" - id: - description: "The id of the corresponding dimension code for the given `dimension_option`" - type: string - limit: - description: "The maximum number of observations requested when filtering on query parameters (limited to 10000). Defaults to 10000 observations." - type: integer - links: - $ref: '#/definitions/ObservationLinks' - observations: - description: "A list of observations found when filtering on query parameters" - type: array - items: - properties: - dimensions: - description: "Contains a list of dimension objects associated with an observation. Each dimension combined with the top level list of dimensions result in this single observation only" - type: object - properties: - : - description: "Each field is a dimension () and will represent a query parameter in the request as long as the query parameter is equal to a wildcard value (*)" - type: object - properties: - href: - description: "A link to the corresponding dimension code for the given `dimension_option`" - example: "http://localhost:8080/codelists/AB12CD34/codes/K02000001" - type: string - id: - description: "The id of the corresponding dimension code for the given `dimension_option`" - type: "string" - label: - description: "The label corresponding to the dimension code for the given `dimension_option`" - type: string - metadata: - description: "Metadata related to the observation found against version of a dataset" - type: array - items: - type: object - properties: - : - description: "A single metadata key-value pair related to the observation found against version of a dataset, for example 'coefficients of variation' or 'data marking'" - type: string - observation: - description: "The observation value for the selection of query parameters (dimensions) chosen" - type: string - required: [observation] - offset: - description: "The offset into the entire list of observations found" - type: integer - total_observations: - description: "The number of observations found" - type: integer - unit_of_measure: - description: "The unit of measure for the dataset observations" - type: string - usage_notes: - description: "A list of usage notes relating to the dataset" - type: array - items: - $ref: '#/definitions/UsageNotes' Publisher: description: "The publisher of the dataset" type: object @@ -2185,31 +1174,6 @@ definitions: collection_id: $ref: '#/definitions/CollectionID' - $ref: "#/definitions/Dataset" - UpdateDimensionOptionRequest: - description: "A cached dimension. (Only used by the Private API)" - type: object - properties: - code: - description: "" - type: string - codelist: - description: "" - type: string - dimension: - description: "The name of the dimension" - type: string - instance_id: - description: "The unique identifier for the instance in which this dimension option is associated to" - type: string - label: - description: "The label for a option" - type: string - option: - description: "The option of the dimension" - type: string - order: - description: "The numerical order for the dimension option" - type: integer UpdateDownloadObject: description: "Object containing information of a downloadable file" type: object @@ -2226,16 +1190,6 @@ definitions: private: description: "The URL to a non public-accessible download" type: string - UpdateInstanceDimension: - description: "Possible fields to be updated against a dimension for an instance resource" - type: object - properties: - description: - description: "The dimension description" - type: string - label: - description: "A human readable label for dimension" - type: string UpdateVersion: description: "An object containing information to be updated on a version resource" type: object @@ -2325,11 +1279,6 @@ definitions: $ref: '#/definitions/Alert' collection_id: $ref: '#/definitions/CollectionID' - dimensions: - description: "A list of codelists for each dimension of this version" - type: array - items: - $ref: '#/definitions/Dimension' downloads: description: "A selection of download objects containing information of downloadable files." type: object @@ -2423,51 +1372,12 @@ definitions: description: "A URL to all versions dor an edition of a dataset" example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/edition/2017/versions" type: string - MetadataLinks: - description: "A list of links related to this resource" - readOnly: true - type: object - properties: - access_right: - $ref: '#/definitions/AccessRightsLink' - self: - $ref: '#/definitions/SelfLink' - spatial: - $ref: '#/definitions/SpatialLink' - version: - $ref: '#/definitions/VersionLink' - website_version: - description: "A link to the location of this version of the dataset on the web" - type: object - properties: - href: - description: "The uri to the location of this version of the dataset on the web" - type: string - ObservationLinks: - description: "A list of links related to this resource" - readOnly: true - type: object - properties: - dataset_metadata: - $ref: '#/definitions/MetadataLink' - self: - $ref: '#/definitions/SelfLink' - version: - $ref: '#/definitions/VersionLink' VersionLinks: description: "A list of links related to this resource" type: object properties: dataset: $ref: '#/definitions/DatasetLink' - dimensions: - readOnly: true - type: object - properties: - href: - description: "A URL to list dimensions for this version" - example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions/2017/versions/2/dimensions" - type: string edition: $ref: '#/definitions/EditionLink' self: @@ -2510,20 +1420,6 @@ definitions: id: description: "The unique id for the latest version of a dataset" type: "string" - MetadataLink: - description: "The version metadata that is associated with this resource" - type: object - properties: - href: - description: "A URL for the version metadata this resource relates to" - type: string - OptionsLink: - description: "A list of links related to this dimension" - type: object - properties: - href: - description: "A URL to a list of options for this dimension" - type: string SelfLink: description: "A link to this resource" readOnly: true @@ -2554,141 +1450,4 @@ definitions: type: string id: description: "The version number this resource relates to" - type: string - MetadataUpdate: - description: "An object containing all editable metadata fields on a dataset and a version resource" - type: object - properties: - alerts: - description: "A list of alerts against a version" - type: array - items: - $ref: '#/definitions/Alert' - canonical_topic: - description: "The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the website taxonomy." - type: string - contacts: - description: "A list containing contact details of statisticians for a dataset" - type: array - items: - $ref: '#/definitions/Contact' - description: - description: "A description for a dataset" - type: string - dimensions: - description: "A list of codelists for each dimension of this version" - type: array - items: - $ref: '#/definitions/Dimension' - keywords: - description: "A list of keywords for a dataset" - type: array - items: - type: "string" - latest_changes: - description: "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition" - type: array - items: - $ref: '#/definitions/LatestChange' - license: - description: "The standard Government license right text for the dataset" - type: string - methodologies: - description: "A list of methodologies for a dataset" - type: array - items: - type: object - properties: - description: - description: "The description of a methodology" - type: string - href: - description: "The url to a methodology" - type: string - title: - description: "The title of a methodology" - type: string - national_statistic: - description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" - type: boolean - next_release: - description: "The next release date for a dataset" - type: string - publications: - description: "A list of publications for a dataset" - type: array - items: - type: object - properties: - description: - description: "The description of a publication" - type: string - href: - description: "The url to a publication" - type: string - title: - description: "The title of a publication" - type: string - qmi: - description: "Object containing information on the quality and methodology index of a dataset" - type: object - properties: - description: - description: "The description of a quality and methodology index" - type: string - href: - description: "The url to a quality and methodology index" - type: string - title: - description: "The title of a quality and methodology index" - type: string - related_content: - description: "A list of objects containing information of content related to a dataset" - type: array - items: - type: object - properties: - href: - description: "The url to related content" - type: string - description: - description: "The description of the related content" - type: string - title: - description: "The title of the related content" - type: string - related_datasets: - description: "A list of objects containing information of datasets related to a dataset" - type: array - items: - type: object - properties: - href: - description: "The url to a related dataset" - type: string - title: - description: "The title of a related dataset" - type: string - release_date: - description: "The release date of this version of the dataset" - type: string - release_frequency: - description: "The release frequency of a dataset" - type: string - subtopics: - description: "A list of subtopic ids that the dataset relates to within the website taxonomy." - type: array - items: - type: "string" - survey: - description: "The name of the survey the dataset was created from." - type: string - title: - description: "The title of the dataset" - example: "CPI" - type: string - unit_of_measure: - description: "The unit of measure for the dataset observations" - type: string - usage_notes: - $ref: '#/definitions/UsageNotes' + type: string \ No newline at end of file From b632e048cff39322ce173b1f9a6933807a0c06ee Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 17 Oct 2023 13:51:31 +0100 Subject: [PATCH 2/9] Update models to conform more closely with application profile (AP) work --- swagger.yaml | 458 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 274 insertions(+), 184 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index d85487b9..60246b06 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -1,5 +1,4 @@ swagger: "2.0" -host: ons.gov.uk info: description: "Used to find information about data published by the ONS. `Datasets` are published in unique `versions`, which are categorized by `edition`. @@ -7,7 +6,6 @@ info: of dimension `options` in a version can be used to retrieve `observation` level data." version: "1.0.0" title: "Explore our data" - contact: me license: name: "Open Government Licence v3.0" url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" @@ -645,131 +643,104 @@ definitions: Dataset: description: "The dataset" type: object - required: ["id", "contacts", "description", "license", "links", "national_statistics", "title"] + required: ["identifier", "@context", "contact_point", "creator", "description", "@id", "issued", "license", "editions", "latest_version", "publisher", "frequency", "spatial_coverage", "spatial_resolution", "state", "temporal_coverage", "temporal_resolution", "title", "type", "@type"] properties: + "@context": + description: "The URL for the JSON-LD context. The field name will be '@context'" + type: string + format: uri canonical_topic: description: "The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the website taxonomy." type: string collection_id: $ref: '#/definitions/CollectionID' - contacts: - description: "A list containing contact details of staticians for a dataset" - type: array - items: - $ref: '#/definitions/Contact' + contact_point: + $ref: '#/definitions/Contact' + creator: + type: string + format: uri description: - description: "A description for a dataset" + description: "A description for a dataset. Could contain markdown" + type: string + "@id": + description: "The URL of the current resource, the same as links.self" + type: string + format: uri + identifier: + description: "The identifier for this dataset. This will form the last part of the URI for this resource" type: string is_based_on: $ref: '#/definitions/IsBasedOn' + issued: + description: "The date the dataset was first issued" + type: string + format: date-time keywords: - description: "A list of keywords for a dataset" + description: "A list of keywords for a dataset, typically to help with Search Engine Optimisation" type: array items: type: "string" license: description: "The standard Government license right text for the dataset" type: string - links: - $ref: '#/definitions/DatasetLinks' - methodologies: - description: "A list of methodologies for a dataset" - type: array - items: - type: object - properties: - description: - description: "The description of a methodology" - type: string - href: - description: "The url to a methodology" - type: string - title: - description: "The title of a methodology" - type: string + default: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" + editions_url: + description: "Link to the list of editions for this dataset" + type: string + format: uri + latest_version_url: + description: "Link to the latest published version of this dataset" + type: string + format: uri national_statistic: description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" type: boolean next_release: description: "The next release date for a dataset" type: string + format: date-time nomis_ref_url: description: "The NOMIS reference url for the dataset" type: string example: "https://www.nomisweb.co.uk/census/2011/ks106ew" - publications: - description: "A list of publications for a dataset" - type: array - items: - type: object - properties: - description: - description: "The description of a publication" - type: string - href: - description: "The url to a publication" - type: string - title: - description: "The title of a publication" - type: string publisher: - $ref: '#/definitions/Publisher' - qmi: - description: "Object containing information on the quality and methodology index of a dataset" - type: object - properties: - description: - description: "The description of a quality and methodology index" - type: string - href: - description: "The url to a quality and methodology index" - type: string - title: - description: "The title of a quality and methodology index" - type: string - related_datasets: - description: "A list of objects containing information of datasets related to a dataset" - type: array - items: - type: object - properties: - href: - description: "The url to a related dataset" - type: string - title: - description: "The title of a related dataset" - type: string - related_content: - description: "A list of objects containing information of content related to a dataset" - type: array - items: - type: object - properties: - href: - description: "The url to related content" - type: string - description: - description: "The description of the related content" - type: string - title: - description: "The title of the related content" - type: string - release_frequency: + #$ref: '#/definitions/Publisher' + type: string + format: uri + frequency: description: "The release frequency of a dataset" type: string - state: - $ref: '#/definitions/State' - subtopics: - description: "A list of subtopic ids that the dataset relates to within the website taxonomy." + spatial_coverage: + description: "The spatial area covered by the dataset, typically a code defining a geographic area which contains all the observed areas" + type: string + spatial_resolution: + description: "A list of the types geographic areas contained in the dataset" type: array items: type: "string" + state: + $ref: '#/definitions/State' + summary: + description: "A short summary of a dataset." + type: string survey: description: "The name of the survey the dataset was created from." type: string - theme: - description: "The theme for a dataset" - type: string + temporal_coverage: + description: "The overall time period covered by the dataset" + type: "string" + format: duration + temporal_resolution: + description: "A list of the types time periods contained in the dataset" + type: array + items: + type: "string" + format: duration + themes: + description: "The themes a dataset relates to. These will be the identifiers for what may be referred to as 'topics' on the website, and used for navigation and breadcrumbs" + type: array + items: + type: string title: description: "The title of the dataset" example: "CPI" @@ -778,17 +749,16 @@ definitions: description: "The type of dataset" example: "cantabular_flexible_table" type: string - unit_of_measure: - description: "The unit of measure for the dataset observations" - type: string - uri: - description: "The uri to the location of this resource on the web" + "@type": + description: "The linked data vocabulary term for a dataset" + default: "dcat:datasetSeries" type: string + Type: description: "The type for a dataset" type: string - enum: [filterable, nomis] - default: "filterable" + enum: [filterable, nomis, cantabular_flexible_table, static] + default: "static" IsBasedOn: description: "Information about the population-type that the dataset is based on (census 2021 only)" type: object @@ -813,20 +783,101 @@ definitions: type: string Edition: type: object + required: ["identifier", "@context", "contact_point", "creator", "description", "@id", "issued", "license", "editions", "latest_version", "publisher", "frequency", "spatial_coverage", "spatial_resolution", "state", "temporal_coverage", "temporal_resolution", "title", "@type"] properties: - edition: - description: "The edition of the dataset" - example: "2017" - readOnly: true + "@context": + description: "The URL for the JSON-LD context. The field name will be '@context'" type: string - id: - description: "An unique id for a dataset edition" - readOnly: true + format: uri + collection_id: + $ref: '#/definitions/CollectionID' + contact_point: + $ref: '#/definitions/Contact' + creator: type: string - links: - $ref: '#/definitions/EditionLinks' + format: uri + dataset_url: + description: "Link to the dataset which contains this edition" + type: string + format: uri + description: + description: "A description for an edition. Could contain markdown" + type: string + "@id": + description: "The URL of the current resource, the same as links.self" + type: string + format: uri + identifier: + description: "The identifier for this edition. This will form the last part of the URI for this resource" + type: string + issued: + description: "The date the edition was first issued" + type: string + format: date-time + keywords: + description: "A list of keywords for an edition, typically to help with Search Engine Optimisation" + type: array + items: + type: "string" + license: + description: "The standard Government license right text for the dataset" + type: string + default: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" + national_statistic: + description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" + type: boolean + next_release: + description: "The next release date for a edition" + type: string + format: date-time + publisher: + #$ref: '#/definitions/Publisher' + type: string + format: uri + frequency: + description: "The release frequency of a edition" + type: string + spatial_coverage: + description: "The spatial area covered by the edition, typically a code defining a geographic area which contains all the observed areas" + type: string + spatial_resolution: + description: "A list of the types geographic areas contained in the edition" + type: array + items: + type: "string" state: $ref: '#/definitions/State' + summary: + description: "A short summary of a edition." + type: string + temporal_coverage: + description: "The overall time period covered by the edition" + type: "string" + format: duration + temporal_resolution: + description: "A list of the types time periods contained in the edition" + type: array + items: + type: "string" + format: duration + themes: + description: "The themes an edition relates to. These will be the identifiers for what may be referred to as 'topics' on the website, and used for navigation and breadcrumbs" + type: array + items: + type: string + title: + description: "The title of the edition" + example: "CPI" + type: string + "@type": + description: "The linked data vocabulary term for an edition" + default: "dcat:dataset" + type: string + versions_url: + description: "Link to the list of versions for this edition" + type: string + format: uri + Editions: type: object properties: @@ -869,40 +920,43 @@ definitions: Instance: type: object properties: - alerts: - description: "A list of alerts against an instance" + version_notes: + description: "Notes describing what is unique to this particular version" readOnly: true - type: array items: - $ref: '#/definitions/Alert' - id: + type: string + identifier: description: "A unique id for an instance" readOnly: true type: string collection_id: $ref: '#/definitions/CollectionID' + creator: + type: string + format: url downloads: description: "A selection of download objects containing information of downloadable files." type: object properties: - csv: + text/csv: $ref: '#/definitions/DownloadObject' - xls: + application/vnd.ms-excel: $ref: '#/definitions/DownloadObject' edition: description: "The edition of the dataset version" type: string + etag: + type: string events: description: "A list of events took place for this job" readOnly: true type: array items: $ref: '#/definitions/Event' - headers: - description: "The header information from a V4 file" - type: array - items: - type: string + issued: + description: "The time when this instance was published" + type: string + format: date-time last_updated: description: "The last time an event happened" readOnly: true @@ -935,20 +989,6 @@ definitions: id: description: "The ID for the dataset edition associated with this instance" type: string - job: - description: "An object describing the ID and URL of the job containing this instance" - readOnly: true - required: ["id", "href"] - type: object - properties: - href: - description: "The URL for the job containing this instance" - example: "http://localhost:21800/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35" - type: string - id: - description: "The ID of the job containing this instance" - example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35 - type: string self: description: "An object describing the ID and URL for a dataset which is associated with this instance" readOnly: true @@ -958,7 +998,7 @@ definitions: description: "The URL for this resource" example: "http://localhost:22000/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f" type: string - spatial: + spatial_resolution: description: "A link object describing the url to a list of geography ranges for the version of the dataset" type: object properties: @@ -978,16 +1018,33 @@ definitions: description: "The ID of the dataset version associated with this instance" example: "042e216a-7822-4fa0-a3d6-e3f5248ffc35" type: string + next_version: + type: string + format: url + previous_version: + type: string + format: url + derived_from: + type: string + format: url + generated_by: + type: string + format: url + described_by: + type: string + format: url release_date: description: "The release date of this version of the dataset" type: string state: $ref: '#/definitions/State' - temporal: + temporal_coverage: $ref: '#/definitions/Temporal' - total_observations: - description: "The number of observations in this instance" - type: integer + temporal_resolution: + description: "" + type: string + table_schema: + $ref: '#/definitions/TableSchema' version: description: "The dataset version number that this instance is associated with, this will only be set once the state has been updated to `edition-confirmed`" readOnly: true @@ -1057,6 +1114,11 @@ definitions: description: "A model for the request and response body for creating a new instance" type: object properties: + dimensions: + description: "A list of codelists for each dimension of this instance" + type: array + items: + $ref: '#/definitions/Codelist' id: description: "A unique id for an instance" readOnly: true @@ -1114,19 +1176,19 @@ definitions: description: "An unique id for a dataset" example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91CD" - $ref: "#/definitions/Version" - Publisher: - description: "The publisher of the dataset" - type: object - properties: - name: - description: "The name of the publisher" - type: string - type: - description: "The type of publisher" - type: string - href: - description: "A link to the publishers homepage" - type: string + # Publisher: + # description: "The publisher of the dataset" + # type: object + # properties: + # name: + # description: "The name of the publisher" + # type: string + # type: + # description: "The type of publisher" + # type: string + # href: + # description: "A link to the publishers homepage" + # type: string State: description: | The state of the resource, can only be one of the following: @@ -1137,6 +1199,35 @@ definitions: * associated (not editions) * published type: string + TableSchema: + description: "The schema defining a CSV on the Web distribution of a dataset version" + type: object + properties: + about_url: + type: string + format: url + column: + type: array + items: + properties: + type: + type: string + datatype: + type: string + name: + type: string + label: + type: string + description: + type: string + title: + type: string + property_url: + type: string + format: url + value_url: + type: string + format: url Temporal: description: "A list of frequencies the dataset covers for a particular period of time" type: array @@ -1272,54 +1363,45 @@ definitions: ] type: object properties: - alerts: - description: "A list of alerts, for example corrections after the resource has been published" + version_notes: + description: "A list of notes, for example corrections after the resource has been published" type: array - items: - $ref: '#/definitions/Alert' + items: + type: string collection_id: $ref: '#/definitions/CollectionID' + "@context": + type: string + format: url + creator: + type: string + format: url downloads: description: "A selection of download objects containing information of downloadable files." type: object properties: - csv: - $ref: '#/definitions/DownloadObject' - csvw: + text/csv: $ref: '#/definitions/DownloadObject' - txt: + application/json+csvm: $ref: '#/definitions/DownloadObject' - xls: + application/vnd.ms-excel: $ref: '#/definitions/DownloadObject' - edition: - description: "The dataset edition for this version" - readOnly: true + etag: type: string - id: + identifier: description: "The identifier for this version of an edition for a dataset" type: string is_based_on: $ref: '#/definitions/IsBasedOn' - dataset_id: - description: "The identifier for the dataset." - type: string - latest_changes: - description: "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition" - type: array - items: - $ref: '#/definitions/LatestChange' links: $ref: '#/definitions/VersionLinks' - lowest_geography: - description: "The lowest geography this dataset is available at (Census datasets only)" - type: string release_date: description: "The release date of this version of the dataset" type: string state: $ref: '#/definitions/State' - temporal: - $ref: '#/definitions/Temporal' + table_schema: + $ref: '#/definitions/TableSchema' type: description: "The type of dataset - e.g. cantabular_flexible_table" type: string @@ -1328,11 +1410,6 @@ definitions: example: 1 readOnly: true type: integer - usage_notes: - description: "A list of usage notes relating to the dataset" - type: array - items: - $ref: '#/definitions/UsageNotes' # Link objects DatasetLinks: description: "A list of links related to this resource" @@ -1382,8 +1459,21 @@ definitions: $ref: '#/definitions/EditionLink' self: $ref: '#/definitions/SelfLink' - spatial: - $ref: '#/definitions/SpatialLink' + next_version: + type: string + format: url + previous_version: + type: string + format: url + derived_from: + type: string + format: url + generated_by: + type: string + format: url + described_by: + type: string + format: url DatasetLink: description: "An object containing the dataset id and link" readOnly: true From 953e4779b81a71102bcd173325ba9155cdc8d90a Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Mon, 23 Oct 2023 18:03:12 +0100 Subject: [PATCH 3/9] Restructure to identify base fields reused across different endpoints --- swagger.yaml | 674 +++++++++++++++++++++++++++------------------------ 1 file changed, 363 insertions(+), 311 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 60246b06..0cfb7872 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -163,12 +163,14 @@ paths: tags: - "Public" summary: "Get a list of datasets" - description: "Returns a list of all datasets provided by the ONS that can be filtered using the filter API" + description: "Returns a list of all datasets in the ONS Data Catalogue" parameters: - $ref: '#/parameters/is_based_on' - $ref: '#/parameters/limit' - $ref: '#/parameters/offset' produces: + - "application/hal+json" + - "application/ld+json" - "application/json" responses: 200: @@ -592,8 +594,8 @@ definitions: CollectionID: description: "The id of the unpublished collection (of datasets) that this dataset is associated with" type: string - Contact: - description: "A list of objects containing contact information for this dataset" + Agent: + description: "A foaf:agent compliant object containing contact information for this resource" type: object properties: email: @@ -605,108 +607,33 @@ definitions: telephone: description: "Telephone number to contact the statistician" type: string - Datasets: - description: "A list of datasets" - type: object + dcatSeriesCore: + description: "Core properties needed for dcat:Dataset and dcat:DatasetSeries objects" properties: - count: - description: "The number of datasets returned" - readOnly: true - type: integer - items: - type: array - items: - $ref: '#/definitions/DatasetResponse' - limit: - description: "The number of datasets requested" - type: integer - offset: - description: "The first row of datasets to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of datasets" - readOnly: true - type: integer - DatasetResponse: - description: "A model for the response body when getting a dataset" - allOf: - - type: object - properties: - id: - description: "An unique id for a dataset" - example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" - readOnly: true - type: string - type: - $ref: "#/definitions/Type" - - $ref: "#/definitions/Dataset" - Dataset: - description: "The dataset" - type: object - required: ["identifier", "@context", "contact_point", "creator", "description", "@id", "issued", "license", "editions", "latest_version", "publisher", "frequency", "spatial_coverage", "spatial_resolution", "state", "temporal_coverage", "temporal_resolution", "title", "type", "@type"] - properties: - "@context": - description: "The URL for the JSON-LD context. The field name will be '@context'" - type: string - format: uri - canonical_topic: - description: "The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the website taxonomy." - type: string - collection_id: - $ref: '#/definitions/CollectionID' - contact_point: - $ref: '#/definitions/Contact' - creator: - type: string - format: uri description: description: "A description for a dataset. Could contain markdown" type: string - "@id": - description: "The URL of the current resource, the same as links.self" - type: string - format: uri identifier: description: "The identifier for this dataset. This will form the last part of the URI for this resource" type: string - is_based_on: - $ref: '#/definitions/IsBasedOn' issued: description: "The date the dataset was first issued" type: string format: date-time - keywords: - description: "A list of keywords for a dataset, typically to help with Search Engine Optimisation" - type: array - items: - type: "string" license: description: "The standard Government license right text for the dataset" type: string default: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" - editions_url: - description: "Link to the list of editions for this dataset" + modified: + description: "The date the dataset was modified" type: string - format: uri - latest_version_url: - description: "Link to the latest published version of this dataset" - type: string - format: uri - national_statistic: - description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" - type: boolean + format: date-time next_release: description: "The next release date for a dataset" type: string format: date-time - nomis_ref_url: - description: "The NOMIS reference url for the dataset" - type: string - example: "https://www.nomisweb.co.uk/census/2011/ks106ew" publisher: - #$ref: '#/definitions/Publisher' - type: string - format: uri + $ref: '#/definitions/Agent' frequency: description: "The release frequency of a dataset" type: string @@ -718,14 +645,9 @@ definitions: type: array items: type: "string" - state: - $ref: '#/definitions/State' summary: description: "A short summary of a dataset." type: string - survey: - description: "The name of the survey the dataset was created from." - type: string temporal_coverage: description: "The overall time period covered by the dataset" type: "string" @@ -736,24 +658,198 @@ definitions: items: type: "string" format: duration - themes: - description: "The themes a dataset relates to. These will be the identifiers for what may be referred to as 'topics' on the website, and used for navigation and breadcrumbs" - type: array - items: - type: string title: description: "The title of the dataset" example: "CPI" type: string - type: - description: "The type of dataset" - example: "cantabular_flexible_table" - type: string - "@type": - description: "The linked data vocabulary term for a dataset" - default: "dcat:datasetSeries" - type: string - + dcatSeriesFull: + description: "Core properties needed for dcat:Dataset and dcat:DatasetSeries objects" + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - type: object + properties: + contact_point: + $ref: '#/definitions/Agent' + keywords: + description: "A list of keywords for a dataset, typically to help with Search Engine Optimisation" + type: array + items: + type: "string" + themes: + description: "The themes a dataset relates to. These will be the identifiers for what may be referred to as 'topics' on the website, and used for navigation and breadcrumbs" + type: array + items: + type: string + dcatVersionCore: + description: "core quality, mangement and relationship fields for describing a dcat:dataset version" + type: object + properties: + distributions: + description: "A selection of download objects containing information of downloadable files." + type: array + items: + allOf: + - type: object + properties: + checksum: + description: "spdx:checksum - some guarantees, hence not etag. Could be a more complex object?" + type: string + - $ref: '#/definitions/DownloadObject' + version: + description: "A number identifying the version for an edition from a dataset" + example: 1 + readOnly: true + type: integer + version_notes: + description: "A list of notes, for example corrections after the resource has been published" + type: array + items: + type: string + dcatVersionFull: + description: "Core properties needed for dcat:Dataset version objects" + allOf: + - $ref: '#/definitions/dcatVersionCore' + - type: object + properties: + next_version: + type: string + format: uri + previous_version: + type: string + format: uri + distributions: + description: "A selection of download objects containing information of downloadable files." + type: array + items: + allOf: + - $ref: '#/definitions/CSVDownload' + - $ref: '#/definitions/DownloadObject' + Datasets: + description: "A list of datasets" + type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + count: + description: "The number of datasets returned" + readOnly: true + type: integer + items: + type: array + items: + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - type: object + properties: + "@id": + $ref: '#/definitions/LDID' + "@type": + allOf: + - $ref: '#/definitions/LDType' + - default: "dcat:datasetSeries" + is_based_on: + $ref: '#/definitions/IsBasedOn' + _links: + $ref: '#/definitions/DatasetListLinks' + national_statistic: + description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" + type: boolean + state: + $ref: '#/definitions/State' + survey: + description: "The name of the survey the dataset was created from." + type: string + type: + $ref: '#/definitions/Type' + _links: + $ref: '#/definitions/ListLinks' + limit: + description: "The number of datasets requested" + type: integer + offset: + description: "The first row of datasets to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" + type: integer + total_count: + description: "The total number of datasets" + readOnly: true + type: integer + # DatasetResponse: + # description: "A model for the response body when getting a dataset" + # allOf: + # - type: object + # properties: + # id: + # description: "An unique id for a dataset" + # example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" + # readOnly: true + # type: string + # type: + # $ref: "#/definitions/Type" + # - $ref: "#/definitions/Dataset" + LDContext: + description: "The URL for the JSON-LD context. The field name will be '@context'" + type: string + format: uri + LDID: + description: "The URL of the current resource, the same as links.self" + type: string + format: uri + LDType: + description: "The linked data vocabulary term for a dataset" + default: "dcat:datasetSeries" + type: string + Dataset: + description: "The dataset" + type: object + required: ["identifier", "@context", "contact_point", "creator", "description", "@id", "issued", "license", "editions", "latest_version", "publisher", "frequency", "spatial_coverage", "spatial_resolution", "state", "temporal_coverage", "temporal_resolution", "title", "type", "@type"] + allOf: + - $ref: '#/definitions/dcatSeriesFull' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + "@id": + $ref: '#/definitions/LDID' + "@type": + $ref: '#/definitions/LDType' + canonical_topic: + description: "The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the website taxonomy." + type: string + collection_id: + description: "Should only be available privately" + allOf: + - $ref: '#/definitions/CollectionID' + _embedded: + type: object + properties: + editions: + description: "Likely described as a 'seeAlso' term" + type: array + items: + type: object + properties: + "@id": + $ref: '#/definitions/LDID' + issued: + description: "The date the edition was first issued" + type: string + format: date-time + etag: + type: string + is_based_on: + $ref: '#/definitions/IsBasedOn' + _links: + $ref: '#/definitions/DatasetLinks' + national_statistic: + description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" + type: boolean + state: + $ref: '#/definitions/State' + survey: + description: "The name of the survey the dataset was created from." + type: string + type: + $ref: '#/definitions/Type' Type: description: "The type for a dataset" type: string @@ -771,116 +867,63 @@ definitions: description: "The type of the dataset" type: string example: "cantabular_table" - DownloadObject: - description: "Object containing information of a downloadable file" + CSVDownload: + description: "Additional fields available for CSV downloads" type: object properties: - href: - description: "The URL to the generated file" + checksum: + description: "spdx:checksum - some guarantees, hence not etag. Could be a more complex object? -- only available for CSVs we expect" type: string - size: - description: "The size of the file in bytes" + described_by: type: string - Edition: + table_schema: + $ref: '#/definitions/TableSchema' + DownloadObject: + description: "Object containing information of a downloadable file" type: object - required: ["identifier", "@context", "contact_point", "creator", "description", "@id", "issued", "license", "editions", "latest_version", "publisher", "frequency", "spatial_coverage", "spatial_resolution", "state", "temporal_coverage", "temporal_resolution", "title", "@type"] properties: - "@context": - description: "The URL for the JSON-LD context. The field name will be '@context'" - type: string - format: uri - collection_id: - $ref: '#/definitions/CollectionID' - contact_point: - $ref: '#/definitions/Contact' - creator: - type: string - format: uri - dataset_url: - description: "Link to the dataset which contains this edition" - type: string - format: uri - description: - description: "A description for an edition. Could contain markdown" - type: string "@id": - description: "The URL of the current resource, the same as links.self" - type: string - format: uri - identifier: - description: "The identifier for this edition. This will form the last part of the URI for this resource" - type: string - issued: - description: "The date the edition was first issued" - type: string - format: date-time - keywords: - description: "A list of keywords for an edition, typically to help with Search Engine Optimisation" - type: array - items: - type: "string" - license: - description: "The standard Government license right text for the dataset" - type: string - default: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" - national_statistic: - description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" - type: boolean - next_release: - description: "The next release date for a edition" - type: string - format: date-time - publisher: - #$ref: '#/definitions/Publisher' - type: string - format: uri - frequency: - description: "The release frequency of a edition" - type: string - spatial_coverage: - description: "The spatial area covered by the edition, typically a code defining a geographic area which contains all the observed areas" - type: string - spatial_resolution: - description: "A list of the types geographic areas contained in the edition" - type: array - items: - type: "string" - state: - $ref: '#/definitions/State' - summary: - description: "A short summary of a edition." + description: "The URL to the generated file" type: string - temporal_coverage: - description: "The overall time period covered by the edition" - type: "string" - format: duration - temporal_resolution: - description: "A list of the types time periods contained in the edition" - type: array - items: - type: "string" - format: duration - themes: - description: "The themes an edition relates to. These will be the identifiers for what may be referred to as 'topics' on the website, and used for navigation and breadcrumbs" - type: array - items: - type: string - title: - description: "The title of the edition" - example: "CPI" + byte_size: + description: "The size of the file in bytes" type: string - "@type": - description: "The linked data vocabulary term for an edition" - default: "dcat:dataset" + media_type: + description: "The MIME type for Accept and Content-Type headers" type: string - versions_url: - description: "Link to the list of versions for this edition" + download_url: + description: "The URL to download the file -- WHY??? isn't this @ID??" type: string - format: uri - + Edition: + type: object + required: ["identifier", "@context", "contact_point", "creator", "description", "@id", "issued", "license", "editions", "latest_version", "publisher", "frequency", "spatial_coverage", "spatial_resolution", "state", "temporal_coverage", "temporal_resolution", "title", "@type"] + allOf: + - $ref: '#/definitions/dcatSeriesFull' + - $ref: '#/definitions/dcatVersionFull' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + "@id": + $ref: '#/definitions/LDID' + "@type": + allOf: + - $ref: '#/definitions/LDType' + - default: 'dcat:dataset' + collection_id: + $ref: '#/definitions/CollectionID' + _links: + $ref: '#/definitions/EditionLinks' + national_statistic: + description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" + type: boolean + state: + $ref: '#/definitions/State' Editions: type: object properties: + "@context": + $ref: '#/definitions/LDContext' count: description: "The number of editions returned for a dataset" readOnly: true @@ -888,7 +931,25 @@ definitions: items: type: array items: - $ref: '#/definitions/Edition' + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - $ref: '#/definitions/dcatVersionCore' + - type: object + properties: + "@id": + $ref: '#/definitions/LDID' + "@type": + allOf: + - $ref: '#/definitions/LDType' + - default: "dcat:dataset" + _links: + $ref: '#/definitions/DatasetListLinks' + state: + $ref: '#/definitions/State' + type: + $ref: '#/definitions/Type' + _links: + $ref: '#/definitions/ListLinks' limit: description: "The number of editions requested for a dataset" type: integer @@ -961,7 +1022,7 @@ definitions: description: "The last time an event happened" readOnly: true type: string - links: + _links: type: object properties: dataset: @@ -1024,15 +1085,6 @@ definitions: previous_version: type: string format: url - derived_from: - type: string - format: url - generated_by: - type: string - format: url - described_by: - type: string - format: url release_date: description: "The release date of this version of the dataset" type: string @@ -1060,6 +1112,8 @@ definitions: type: array items: $ref: '#/definitions/Instance' + _links: + $ref: '#/definitions/ListLinks' limit: description: "The number of instances requested" type: integer @@ -1084,6 +1138,22 @@ definitions: description: "The type of change" type: string example: "summary of changes" + ListLinks: + description: "The _links structure provided on all list endpoints" + type: object + properties: + self: + $ref: '#/definitions/SelfLink' + next: + type: object + properties: + href: + type: string + prev: + type: object + properties: + href: + type: string NewDatasetResponse: description: "A model for the response body when creating a new dataset" type: object @@ -1176,19 +1246,6 @@ definitions: description: "An unique id for a dataset" example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91CD" - $ref: "#/definitions/Version" - # Publisher: - # description: "The publisher of the dataset" - # type: object - # properties: - # name: - # description: "The name of the publisher" - # type: string - # type: - # description: "The type of publisher" - # type: string - # href: - # description: "A link to the publishers homepage" - # type: string State: description: | The state of the resource, can only be one of the following: @@ -1210,16 +1267,16 @@ definitions: type: array items: properties: - type: + component_type: type: string datatype: type: string name: type: string - label: - type: string - description: - type: string + # label: + # type: string + # description: + # type: string title: type: string property_url: @@ -1228,6 +1285,11 @@ definitions: value_url: type: string format: url + codelist_url: + type: string + format: url + sub_property_of: + type: string Temporal: description: "A list of frequencies the dataset covers for a particular period of time" type: array @@ -1319,24 +1381,11 @@ definitions: example: 1 readOnly: true type: integer - usage_notes: - description: "A list of usage notes relating to the dataset" - type: array - items: - $ref: '#/definitions/UsageNotes' - UsageNotes: - description: "A note relating to the dataset. This will appear in downloaded datasets" - type: object - properties: - title: - description: "The title of the note" - type: string - note: - description: "The content of the note" - type: string Versions: type: object properties: + "@context": + $ref: '#/definitions/LDContext' count: description: "The number of versions returned for an edition of a dataset" readOnly: true @@ -1345,7 +1394,26 @@ definitions: description: "An array of Datasets" type: array items: - $ref: '#/definitions/Version' + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - $ref: '#/definitions/dcatVersionCore' + - type: object + properties: + etag: + type: string + "@id": + $ref: '#/definitions/LDID' + "@type": + $ref: '#/definitions/LDType' + _links: + type: object + properties: + self: + $ref: '#/definitions/SelfLink' + state: + $ref: '#/definitions/State' + _links: + $ref: '#/definitions/ListLinks' limit: description: "The number of versions requested for an edition of a dataset" type: integer @@ -1361,62 +1429,39 @@ definitions: required: [ release_date, ] - type: object - properties: - version_notes: - description: "A list of notes, for example corrections after the resource has been published" - type: array - items: + allOf: + - $ref: '#/definitions/dcatSeriesFull' + - $ref: '#/definitions/dcatVersionFull' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + "@id": + $ref: '#/definitions/LDID' + "@type": + $ref: '#/definitions/LDType' + etag: type: string - collection_id: - $ref: '#/definitions/CollectionID' - "@context": - type: string - format: url - creator: - type: string - format: url - downloads: - description: "A selection of download objects containing information of downloadable files." - type: object - properties: - text/csv: - $ref: '#/definitions/DownloadObject' - application/json+csvm: - $ref: '#/definitions/DownloadObject' - application/vnd.ms-excel: - $ref: '#/definitions/DownloadObject' - etag: - type: string - identifier: - description: "The identifier for this version of an edition for a dataset" - type: string - is_based_on: - $ref: '#/definitions/IsBasedOn' - links: - $ref: '#/definitions/VersionLinks' - release_date: - description: "The release date of this version of the dataset" - type: string - state: - $ref: '#/definitions/State' - table_schema: - $ref: '#/definitions/TableSchema' - type: - description: "The type of dataset - e.g. cantabular_flexible_table" - type: string - version: - description: "A number identifying the version for an edition from a dataset" - example: 1 - readOnly: true - type: integer + is_based_on: + $ref: '#/definitions/IsBasedOn' + _links: + $ref: '#/definitions/VersionLinks' + type: + $ref: '#/definitions/Type' + next_version: + type: string + format: uri + previous_version: + type: string + format: uri + state: + $ref: '#/definitions/State' + # Link objects DatasetLinks: description: "A list of links related to this resource" type: object properties: - access_rights: - $ref: '#/definitions/AccessRightsLink' editions: readOnly: true type: object @@ -1429,8 +1474,14 @@ definitions: $ref: '#/definitions/LatestVersionLink' self: $ref: '#/definitions/SelfLink' - taxonomy: - $ref: '#/definitions/TaxonomyLink' + DatasetListLinks: + description: "A list of links related to this resource, in the context of a list of datasets" + type: object + properties: + latest_version: + $ref: '#/definitions/LatestVersionLink' + self: + $ref: '#/definitions/SelfLink' EditionLinks: description: "A list of links related to this resource" readOnly: true @@ -1459,21 +1510,22 @@ definitions: $ref: '#/definitions/EditionLink' self: $ref: '#/definitions/SelfLink' - next_version: - type: string - format: url - previous_version: - type: string - format: url - derived_from: - type: string - format: url - generated_by: - type: string - format: url - described_by: - type: string - format: url + next: + type: object + properties: + href: + type: string + format: url + id: + type: string + prev: + type: object + properties: + href: + type: string + format: url + id: + type: string DatasetLink: description: "An object containing the dataset id and link" readOnly: true From e04c180bd46326ef730226d4bca3bf449a3c1628 Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Fri, 27 Oct 2023 16:48:24 +0100 Subject: [PATCH 4/9] Move pagination in swagger spec to reusable field --- swagger.yaml | 323 +++++++++++++++++++++++++++------------------------ 1 file changed, 168 insertions(+), 155 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 0cfb7872..6231ec3f 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -214,11 +214,15 @@ paths: description: "The dataset contains all high level information, for additional details see editions or versions of a dataset. " parameters: - $ref: '#/parameters/id' + produces: + - "application/hal+json" + - "application/ld+json" + - "application/json" responses: 200: description: "A json object for a single Dataset" schema: - $ref: '#/definitions/DatasetResponse' + $ref: '#/definitions/Dataset' 404: description: "No dataset was found using the id provided" 500: @@ -268,6 +272,10 @@ paths: - $ref: '#/parameters/id' - $ref: '#/parameters/limit' - $ref: '#/parameters/offset' + produces: + - "application/hal+json" + - "application/ld+json" + - "application/json" responses: 200: description: "A json list containing all editions for a dataset" @@ -288,6 +296,10 @@ paths: parameters: - $ref: '#/parameters/edition' - $ref: '#/parameters/id' + produces: + - "application/hal+json" + - "application/ld+json" + - "application/json" responses: 200: description: "A json object containing an edition" @@ -310,6 +322,10 @@ paths: - $ref: '#/parameters/id' - $ref: '#/parameters/limit' - $ref: '#/parameters/offset' + produces: + - "application/hal+json" + - "application/ld+json" + - "application/json" responses: 200: description: "A json list containing all versions for a set type of dataset and edition" @@ -363,6 +379,10 @@ paths: - $ref: '#/parameters/edition' - $ref: '#/parameters/id' - $ref: '#/parameters/version' + produces: + - "application/hal+json" + - "application/ld+json" + - "application/json" responses: 200: description: "A json object containing the edition and version of a dataset" @@ -571,12 +591,6 @@ responses: UnauthorisedError: description: "The token provided is unauthorised to carry out this operation" definitions: - AccessRightsLink: - type: object - properties: - href: - description: "A url to the standard Government access right text for the dataset" - type: string Alert: description: "Important information relating to a version of a dataset" type: object @@ -663,7 +677,7 @@ definitions: example: "CPI" type: string dcatSeriesFull: - description: "Core properties needed for dcat:Dataset and dcat:DatasetSeries objects" + description: "All properties needed for full dcat:DatasetSeries or dcat:Dataset objects" allOf: - $ref: '#/definitions/dcatSeriesCore' - type: object @@ -706,7 +720,7 @@ definitions: items: type: string dcatVersionFull: - description: "Core properties needed for dcat:Dataset version objects" + description: "All properties needed for complete dcat:Dataset version objects" allOf: - $ref: '#/definitions/dcatVersionCore' - type: object @@ -727,65 +741,39 @@ definitions: Datasets: description: "A list of datasets" type: object - properties: - "@context": - $ref: '#/definitions/LDContext' - count: - description: "The number of datasets returned" - readOnly: true - type: integer - items: - type: array - items: - allOf: - - $ref: '#/definitions/dcatSeriesCore' - - type: object - properties: - "@id": - $ref: '#/definitions/LDID' - "@type": - allOf: - - $ref: '#/definitions/LDType' - - default: "dcat:datasetSeries" - is_based_on: - $ref: '#/definitions/IsBasedOn' - _links: - $ref: '#/definitions/DatasetListLinks' - national_statistic: - description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" - type: boolean - state: - $ref: '#/definitions/State' - survey: - description: "The name of the survey the dataset was created from." - type: string - type: - $ref: '#/definitions/Type' - _links: - $ref: '#/definitions/ListLinks' - limit: - description: "The number of datasets requested" - type: integer - offset: - description: "The first row of datasets to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of datasets" - readOnly: true - type: integer - # DatasetResponse: - # description: "A model for the response body when getting a dataset" - # allOf: - # - type: object - # properties: - # id: - # description: "An unique id for a dataset" - # example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC" - # readOnly: true - # type: string - # type: - # $ref: "#/definitions/Type" - # - $ref: "#/definitions/Dataset" + allOf: + - $ref: '#/definitions/ListPagination' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + items: + type: array + items: + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - type: object + properties: + "@id": + $ref: '#/definitions/LDID' + "@type": + allOf: + - $ref: '#/definitions/LDType' + - default: "dcat:datasetSeries" + is_based_on: + $ref: '#/definitions/IsBasedOn' + _links: + $ref: '#/definitions/DatasetListLinks' + national_statistic: + description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" + type: boolean + state: + $ref: '#/definitions/State' + survey: + description: "The name of the survey the dataset was created from." + type: string + type: + $ref: '#/definitions/Type' LDContext: description: "The URL for the JSON-LD context. The field name will be '@context'" type: string @@ -907,59 +895,50 @@ definitions: "@id": $ref: '#/definitions/LDID' "@type": - allOf: - - $ref: '#/definitions/LDType' - - default: 'dcat:dataset' - collection_id: - $ref: '#/definitions/CollectionID' + $ref: '#/definitions/LDType' + etag: + type: string + is_based_on: + $ref: '#/definitions/IsBasedOn' _links: $ref: '#/definitions/EditionLinks' - national_statistic: - description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" - type: boolean + type: + $ref: '#/definitions/Type' + next_edition: + type: string + format: uri + previous_edition: + type: string + format: uri state: $ref: '#/definitions/State' + Editions: type: object - properties: - "@context": - $ref: '#/definitions/LDContext' - count: - description: "The number of editions returned for a dataset" - readOnly: true - type: integer - items: - type: array - items: - allOf: - - $ref: '#/definitions/dcatSeriesCore' - - $ref: '#/definitions/dcatVersionCore' - - type: object - properties: - "@id": - $ref: '#/definitions/LDID' - "@type": - allOf: - - $ref: '#/definitions/LDType' - - default: "dcat:dataset" - _links: - $ref: '#/definitions/DatasetListLinks' - state: - $ref: '#/definitions/State' - type: - $ref: '#/definitions/Type' - _links: - $ref: '#/definitions/ListLinks' - limit: - description: "The number of editions requested for a dataset" - type: integer - offset: - description: "The first row of editions for a dataset to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of editions against a dataset" - readOnly: true - type: integer + allOf: + - $ref: '#/definitions/ListPagination' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + items: + type: array + items: + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - $ref: '#/definitions/dcatVersionCore' + - type: object + properties: + etag: + type: string + "@id": + $ref: '#/definitions/LDID' + "@type": + $ref: '#/definitions/LDType' + _links: + $ref: '#/definitions/SelfLink' + state: + $ref: '#/definitions/State' Event: type: object properties: @@ -1154,6 +1133,25 @@ definitions: properties: href: type: string + ListPagination: + description: "The fields required on a list endpoint to facilitate pagination" + properties: + _links: + $ref: '#/definitions/ListLinks' + count: + description: "The number of versions returned for an edition of a dataset" + readOnly: true + type: integer + limit: + description: "The number of editions requested for a dataset" + type: integer + offset: + description: "The first row of editions for a dataset to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" + type: integer + total_count: + description: "The total number of editions against a dataset" + readOnly: true + type: integer NewDatasetResponse: description: "A model for the response body when creating a new dataset" type: object @@ -1382,48 +1380,32 @@ definitions: readOnly: true type: integer Versions: - type: object - properties: - "@context": - $ref: '#/definitions/LDContext' - count: - description: "The number of versions returned for an edition of a dataset" - readOnly: true - type: integer - items: - description: "An array of Datasets" - type: array - items: - allOf: - - $ref: '#/definitions/dcatSeriesCore' - - $ref: '#/definitions/dcatVersionCore' - - type: object - properties: - etag: - type: string - "@id": - $ref: '#/definitions/LDID' - "@type": - $ref: '#/definitions/LDType' - _links: - type: object + # type: object + allOf: + - $ref: '#/definitions/ListPagination' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + items: + description: "An array of Datasets" + type: array + items: + allOf: + - $ref: '#/definitions/dcatSeriesCore' + - $ref: '#/definitions/dcatVersionCore' + - type: object properties: - self: + etag: + type: string + "@id": + $ref: '#/definitions/LDID' + "@type": + $ref: '#/definitions/LDType' + _links: $ref: '#/definitions/SelfLink' - state: - $ref: '#/definitions/State' - _links: - $ref: '#/definitions/ListLinks' - limit: - description: "The number of versions requested for an edition of a dataset" - type: integer - offset: - description: "The first row of versions for an edition of a dataset to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of versions for an edition of a dataset" - readOnly: true - type: integer + state: + $ref: '#/definitions/State' Version: description: "An object containing information about published datasets from the ONS" required: [ @@ -1489,6 +1471,14 @@ definitions: properties: dataset: $ref: '#/definitions/DatasetLink' + editions: + readOnly: true + type: object + properties: + href: + description: "A URL to all editions for this dataset" + example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions" + type: string latest_version: $ref: '#/definitions/LatestVersionLink' self: @@ -1500,6 +1490,22 @@ definitions: description: "A URL to all versions dor an edition of a dataset" example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/edition/2017/versions" type: string + next: + type: object + properties: + href: + type: string + format: url + id: + type: string + prev: + type: object + properties: + href: + type: string + format: url + id: + type: string VersionLinks: description: "A list of links related to this resource" type: object @@ -1510,6 +1516,13 @@ definitions: $ref: '#/definitions/EditionLink' self: $ref: '#/definitions/SelfLink' + versions: + type: object + properties: + href: + description: "A URL to all versions dor an edition of a dataset" + example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/edition/2017/versions" + type: string next: type: object properties: From a5443cb36fad3a0b4e5421bfeca7374e00a261be Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 31 Oct 2023 10:45:17 +0000 Subject: [PATCH 5/9] Add _embedded to /editions/{id} spec --- swagger.yaml | 41 +++++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 6231ec3f..0830dd57 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -622,7 +622,7 @@ definitions: description: "Telephone number to contact the statistician" type: string dcatSeriesCore: - description: "Core properties needed for dcat:Dataset and dcat:DatasetSeries objects" + description: "Core properties needed for dcat:Dataset and dcat:DatasetSeries objects. Used by both list and resource endpoints" properties: description: description: "A description for a dataset. Could contain markdown" @@ -677,7 +677,7 @@ definitions: example: "CPI" type: string dcatSeriesFull: - description: "All properties needed for full dcat:DatasetSeries or dcat:Dataset objects" + description: "All properties needed for full dcat:DatasetSeries or dcat:Dataset objects. Used only by resource endpoints, not lists" allOf: - $ref: '#/definitions/dcatSeriesCore' - type: object @@ -695,7 +695,7 @@ definitions: items: type: string dcatVersionCore: - description: "core quality, mangement and relationship fields for describing a dcat:dataset version" + description: "core quality, mangement and relationship fields for describing a dcat:dataset version. Used by both list and resource endpoints" type: object properties: distributions: @@ -720,7 +720,7 @@ definitions: items: type: string dcatVersionFull: - description: "All properties needed for complete dcat:Dataset version objects" + description: "All properties needed for complete dcat:Dataset version objects. Used only by resource endpoints, not lists" allOf: - $ref: '#/definitions/dcatVersionCore' - type: object @@ -784,7 +784,7 @@ definitions: format: uri LDType: description: "The linked data vocabulary term for a dataset" - default: "dcat:datasetSeries" + default: "dcat:dataset" type: string Dataset: description: "The dataset" @@ -799,7 +799,9 @@ definitions: "@id": $ref: '#/definitions/LDID' "@type": - $ref: '#/definitions/LDType' + allOf: + - $ref: '#/definitions/LDType' + - default: "dcat:datasetSeries" canonical_topic: description: "The canonical topic id for this dataset. This indicates which topic this dataset belongs to within the website taxonomy." type: string @@ -898,6 +900,33 @@ definitions: $ref: '#/definitions/LDType' etag: type: string + _embedded: + type: object + properties: + versions: + description: "Likely described as a 'seeAlso' term" + type: array + items: + type: object + properties: + "@id": + $ref: '#/definitions/LDID' + issued: + description: "The date the edition was first issued" + type: string + format: date-time + etag: + type: string + version: + description: "A number identifying the version for an edition from a dataset" + example: 1 + readOnly: true + type: integer + version_notes: + description: "A list of notes, for example corrections after the resource has been published" + type: array + items: + type: string is_based_on: $ref: '#/definitions/IsBasedOn' _links: From 402f351cb127e6110b397f0e156169877cd0882c Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 31 Oct 2023 14:09:03 +0000 Subject: [PATCH 6/9] Update instance spec to reflect dcat changes and add POST /editions --- swagger.yaml | 354 +++++++++++++++------------------------------------ 1 file changed, 100 insertions(+), 254 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 0830dd57..4fb78851 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -34,9 +34,9 @@ parameters: in: body schema: $ref: '#/definitions/Event' - id: - name: id - description: "Id that represents a dataset" + identifier: + name: identifier + description: "Identifier that represents a dataset" in: path required: true type: string @@ -183,14 +183,14 @@ paths: description: "No dataset was found with the popultation-type provided" 500: $ref: '#/responses/InternalError' - /datasets/{id}: + /datasets/{identifier}: post: tags: - "Private user" summary: "Create a dataset" description: "Create a dataset provided by the ONS that can be filtered using the filter API" parameters: - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/new_dataset' produces: - "application/json" @@ -213,7 +213,7 @@ paths: summary: "Get a dataset" description: "The dataset contains all high level information, for additional details see editions or versions of a dataset. " parameters: - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' produces: - "application/hal+json" - "application/ld+json" @@ -233,7 +233,7 @@ paths: summary: "Update a dataset" description: "Update the metadata for the next release of the dataset. The dataset contains all high level information, for additional details see editions or versions of a dataset." parameters: - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/update_dataset' responses: 200: @@ -252,7 +252,7 @@ paths: summary: "Delete a dataset" description: "Delete an existing dataset" parameters: - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' responses: 204: description: "The dataset was successfully deleted" @@ -262,14 +262,37 @@ paths: description: "Forbidden to delete dataset, already published" 500: $ref: '#/responses/InternalError' - /datasets/{id}/editions: + /datasets/{identifier}/editions: + post: + tags: + - "Private user" + summary: "Create an edition of a dataset" + description: "Create an edition of a dataset" + parameters: + - $ref: '#/parameters/identifier' + - $ref: '#/parameters/new_dataset' + produces: + - "application/json" + responses: + 201: + description: "A json object containing an edition which has been created" + schema: + $ref: '#/definitions/Edition' + 400: + description: "Invalid request body" + 401: + description: "Unauthorised to create/overwrite edition" + 403: + description: "Forbidden to overwrite edition, already published" + 500: + $ref: '#/responses/InternalError' get: tags: - "Public" summary: "Get a list of editions of a dataset" description: "Get a list of editions of a type of dataset" parameters: - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/limit' - $ref: '#/parameters/offset' produces: @@ -287,7 +310,7 @@ paths: description: "No editions were found for the id provided" 500: $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}: + /datasets/{identifier}/editions/{edition}: get: tags: - "Public" @@ -295,7 +318,7 @@ paths: description: "The edition contains a link to all versions" parameters: - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' produces: - "application/hal+json" - "application/ld+json" @@ -311,7 +334,7 @@ paths: description: "No edition of a dataset was found using the id and edition provided" 500: $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}/versions: + /datasets/{identifier}/editions/{edition}/versions: get: tags: - "Public" @@ -319,7 +342,7 @@ paths: description: "Get a list of all versions for an edition of a dataset" parameters: - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/limit' - $ref: '#/parameters/offset' produces: @@ -340,14 +363,14 @@ paths: description: "No versions found using the id and edition provided" 500: $ref: '#/responses/InternalError' - /datasets/{id}/editions/{edition}/versions/{version}: + /datasets/{identifier}/editions/{edition}/versions/{version}: put: tags: - "Private user" summary: "Update a version" description: "Update a version for an edition of a dataset, if the state is changed to associated or published, the parent documents(dataset and edition resources) will also be updated. A version can only be updated if the state is not published" parameters: - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/edition' - $ref: '#/parameters/version' - $ref: '#/parameters/version_update' @@ -377,7 +400,7 @@ paths: description: "Get a specific version of an edition of a dataset" parameters: - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/version' produces: - "application/hal+json" @@ -408,7 +431,7 @@ paths: description: "detaches a version from a collection. Effectively a soft delete." parameters: - $ref: '#/parameters/edition' - - $ref: '#/parameters/id' + - $ref: '#/parameters/identifier' - $ref: '#/parameters/version' security: - InternalAPIKey: [] @@ -988,149 +1011,51 @@ definitions: type: string Instance: type: object - properties: - version_notes: - description: "Notes describing what is unique to this particular version" - readOnly: true - items: + allOf: + - $ref: '#/definitions/dcatSeriesFull' + - $ref: '#/definitions/dcatVersionFull' + - type: object + properties: + collection_id: + $ref: '#/definitions/CollectionID' + etag: type: string - identifier: - description: "A unique id for an instance" - readOnly: true - type: string - collection_id: - $ref: '#/definitions/CollectionID' - creator: - type: string - format: url - downloads: - description: "A selection of download objects containing information of downloadable files." - type: object - properties: - text/csv: - $ref: '#/definitions/DownloadObject' - application/vnd.ms-excel: - $ref: '#/definitions/DownloadObject' - edition: - description: "The edition of the dataset version" - type: string - etag: - type: string - events: - description: "A list of events took place for this job" - readOnly: true - type: array - items: - $ref: '#/definitions/Event' - issued: - description: "The time when this instance was published" - type: string - format: date-time - last_updated: - description: "The last time an event happened" - readOnly: true - type: string - _links: - type: object - properties: - dataset: - description: "An object describing the ID and URL for a dataset which is associated with this instance" - readOnly: true - type: object - properties: - href: - description: "The URL for the dataset associated with this instance" - example: "http://localhost:22000/datasets/95c4669b-3ae9-4ba7-b690-87e890a1c67c" - type: string - id: - description: "The ID of the dataset associated with this instance" - example: "95c4669b-3ae9-4ba7-b690-87e890a1c67c" - type: string - edition: - description: "An object describing the ID and URL for the dataset edition that is associated with this instance" - readOnly: true - type: object - properties: - href: - description: "The URL for the dataset edition associated with this instance" - example: "http://localhost:22000/datasets/95c4669b-3ae9-4ba7-b690-87e890a1c67c/editions/2017" - type: string - id: - description: "The ID for the dataset edition associated with this instance" - type: string - self: - description: "An object describing the ID and URL for a dataset which is associated with this instance" - readOnly: true - type: object - properties: - href: - description: "The URL for this resource" - example: "http://localhost:22000/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f" - type: string - spatial_resolution: - description: "A link object describing the url to a list of geography ranges for the version of the dataset" - type: object - properties: - href: - description: "A url to a list of geography ranges for the version of the dataset" - type: string - version: - description: "An object describing the ID and URL of the dataset version associated with this instance" - readOnly: true - type: object + events: + description: "A list of events took place for this job" + readOnly: true + type: array + items: + $ref: '#/definitions/Event' + last_updated: + description: "The last time an event happened" + readOnly: true + type: string + _links: + allOf: + - $ref: '#/definitions/VersionLinks' + - type: object properties: - href: - description: "The URL for the dataset version associated with this instance" - example: 'http://localhost:21800/dataset/042e216a-7822-4fa0-a3d6-e3f5248ffc35/edition/2017/version/1' - type: string - id: - description: "The ID of the dataset version associated with this instance" - example: "042e216a-7822-4fa0-a3d6-e3f5248ffc35" - type: string - next_version: - type: string - format: url - previous_version: - type: string - format: url - release_date: - description: "The release date of this version of the dataset" - type: string - state: - $ref: '#/definitions/State' - temporal_coverage: - $ref: '#/definitions/Temporal' - temporal_resolution: - description: "" - type: string - table_schema: - $ref: '#/definitions/TableSchema' - version: - description: "The dataset version number that this instance is associated with, this will only be set once the state has been updated to `edition-confirmed`" - readOnly: true - type: integer + version: + description: "Version link is needed separately on an Instance as the self link will use the instance ID rather than version path." + type: object + readOnly: true + properties: + href: + type: string + job: + $ref: '#/definitions/JobLink' + state: + $ref: '#/definitions/State' Instances: description: "A list of instance resources, if query parameter state is set return all instances with that state" type: object properties: - count: - description: "The number of instances returned" - type: integer items: type: array items: $ref: '#/definitions/Instance' _links: $ref: '#/definitions/ListLinks' - limit: - description: "The number of instances requested" - type: integer - offset: - description: "The first row of instances to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter" - type: integer - total_count: - description: "The total number of instances" - type: integer LatestChange: description: "A single change between this version and the previous version of an edition for a dataset" type: object @@ -1210,57 +1135,16 @@ definitions: NewInstance: description: "A model for the request and response body for creating a new instance" type: object - properties: - dimensions: - description: "A list of codelists for each dimension of this instance" - type: array - items: - $ref: '#/definitions/Codelist' - id: - description: "A unique id for an instance" - readOnly: true - type: string - links: - type: object + allOf: + - $ref: '#/definitions/Instance' + - type: object properties: - dataset: - description: "An object describing the ID and URL for a dataset which is associated with this instance" - type: object - properties: - href: - description: "The URL for the dataset associated with this instance" - example: "http://localhost:22000/datasets/95c4669b-3ae9-4ba7-b690-87e890a1c67c" - type: string - id: - description: "The ID of the dataset associated with this instance" - example: "95c4669b-3ae9-4ba7-b690-87e890a1c67c" - type: string - job: - description: "An object describing the ID and URL of the job containing this instance" - required: ["id", "href"] - type: object - properties: - href: - description: "The URL for the job containing this instance" - example: "http://localhost:21800/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35" - type: string - id: - description: "The ID of the job containing this instance" - example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35 - type: string - self: - description: "An object describing the ID and URL for a dataset which is associated with this instance" - readOnly: true - type: object - properties: - href: - description: "The URL for this resource" - example: "http://localhost:22000/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f" - type: string - state: - description: "The state of the resource, this can only have a value of `created`" - type: string - readOnly: true + dimensions: + description: "A list of codelists for each dimension of this instance" + type: array + items: + $ref: '#/definitions/Codelist' + NewVersionResponse: description: "A model for the response body when creating a new version for an edition of a dataset" allOf: @@ -1268,10 +1152,6 @@ definitions: properties: collection_id: $ref: '#/definitions/CollectionID' - id: - type: string - description: "An unique id for a dataset" - example: "DE3BC0B6-D6C4-4E20-917E-95D7EA8C91CD" - $ref: "#/definitions/Version" State: description: | @@ -1354,62 +1234,12 @@ definitions: collection_id: $ref: '#/definitions/CollectionID' - $ref: "#/definitions/Dataset" - UpdateDownloadObject: - description: "Object containing information of a downloadable file" - type: object - properties: - href: - description: "The URL to the generated file" - type: string - size: - description: "The size of the file in bytes" - type: string - public: - description: "The URL to a public-accessible download" - type: string - private: - description: "The URL to a non public-accessible download" - type: string UpdateVersion: description: "An object containing information to be updated on a version resource" type: object properties: - alerts: - description: "A list of alerts, for example corrections after the resource has been published" - type: array - items: - $ref: '#/definitions/Alert' - collection_id: - $ref: '#/definitions/CollectionID' - downloads: - description: "A selection of download objects containing information of downloadable files. These can only be updated via an authorised caller." - type: object - properties: - csv: - $ref: '#/definitions/DownloadObject' - xls: - $ref: '#/definitions/DownloadObject' - latest_changes: - description: "A list of changes between version of an edition for a dataset and the previous version of the same dataset edition" - type: array - items: - $ref: '#/definitions/LatestChange' - links: - $ref: '#/definitions/VersionLinks' - release_date: - description: "The release date of this version of the dataset" - type: string - state: - $ref: '#/definitions/State' - temporal: - $ref: '#/definitions/Temporal' - version: - description: "A number identifying the version for an edition from a dataset" - example: 1 - readOnly: true - type: integer + $ref: '#/definitions/Version' Versions: - # type: object allOf: - $ref: '#/definitions/ListPagination' - type: object @@ -1462,9 +1292,11 @@ definitions: next_version: type: string format: uri + readOnly: true previous_version: type: string format: uri + readOnly: true state: $ref: '#/definitions/State' @@ -1538,6 +1370,7 @@ definitions: VersionLinks: description: "A list of links related to this resource" type: object + readOnly: true properties: dataset: $ref: '#/definitions/DatasetLink' @@ -1592,6 +1425,19 @@ definitions: id: description: "The unique id for the dataset edition for a version" type: string + JobLink: + description: "An object describing the ID and URL of the job containing this instance" + required: ["id", "href"] + type: object + properties: + href: + description: "The URL for the job containing this instance" + example: "http://localhost:21800/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35" + type: string + id: + description: "The ID of the job containing this instance" + example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35 + type: string LatestVersionLink: description: "An object containing the latest version id and link" type: object From a7efc02bbd6c852857ce58fae282796af6f67527 Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 31 Oct 2023 14:56:39 +0000 Subject: [PATCH 7/9] Reintroduce dimensions endpoints for census datasets in spec --- swagger.yaml | 444 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 435 insertions(+), 9 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 4fb78851..6e07ed14 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -1,11 +1,8 @@ swagger: "2.0" info: - description: "Used to find information about data published by the ONS. - `Datasets` are published in unique `versions`, which are categorized by `edition`. - Data in each version is broken down by `dimensions`, and a unique combination - of dimension `options` in a version can be used to retrieve `observation` level data." - version: "1.0.0" title: "Explore our data" + description: "Used to find information about data published by the ONS. `Datasets` are published in unique `versions`, which are categorized by `edition`. Data in each version is broken down by `dimensions`, and a unique combination of dimension `options` in a version can be used to retrieve `observation` level data." + version: "1.0.0" license: name: "Open Government Licence v3.0" url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/" @@ -22,6 +19,32 @@ parameters: description: "A unique id for a dataset to filter on" in: query type: string + dimension: + name: dimension + description: "A dimension from a dataset" + in: path + required: true + type: string + dimension_options: + description: "The name of the dimension option and a single value; each option (dimension) and corresponding value (code) must exist against the version - e.g. `age=30` or one of the dimension options can be represented by a wildcard value `*` e.g. `geography=*`" + name: "" + in: query + required: true + type: string + patch_options: + required: true + name: patch + schema: + $ref: '#/definitions/PatchOptions' + description: "A list of patch operations for a dimension option" + in: body + patch_dimensions: + required: true + name: patch + schema: + $ref: '#/definitions/PatchDimensions' + description: "A list of patch operations for a dimension" + in: body edition: name: edition description: "An edition of a dataset" @@ -451,6 +474,65 @@ paths: description: "No version was found for an edition of a dataset using the id, edition and version provided" 500: $ref: '#/responses/InternalError' + /datasets/{identifier}/editions/{edition}/versions/{version}/dimensions: + get: + tags: + - "Public" + summary: "Get a list of dimensions from a dataset" + description: "Get all dimensions which are used in the dataset" + parameters: + - $ref: '#/parameters/edition' + - $ref: '#/parameters/identifier' + - $ref: '#/parameters/version' + - $ref: '#/parameters/limit' + - $ref: '#/parameters/offset' + responses: + 200: + description: "A json list of dimensions" + schema: + $ref: '#/definitions/Dimensions' + 400: + description: | + Invalid request, reasons can be one of the following: + * dataset id was incorrect + * edition was incorrect + * version was incorrect + 404: + description: "No dimensions found for version of an edition of a dataset using the id, edition and version provided" + 500: + $ref: '#/responses/InternalError' + /datasets/{identifier}/editions/{edition}/versions/{version}/dimensions/{dimension}/options: + get: + tags: + - "Public" + summary: "Get a list of options from a dimension" + description: "Get a list of options which appear in this dimension and dataset. By default all options are returned, but a subset can be requested by providing offset and limit query parameters, or by providing the list of option IDs, only the IDs that are found will be returned." + parameters: + - $ref: '#/parameters/dimension' + - $ref: '#/parameters/edition' + - $ref: '#/parameters/identifier' + - $ref: '#/parameters/version' + - $ref: '#/parameters/limit' + - $ref: '#/parameters/offset' + - $ref: '#/parameters/ids' + responses: + 200: + description: "Json object containing all options for a dimension" + schema: + $ref: '#/definitions/DimensionOptions' + 400: + description: | + Invalid request, reasons can be one of the following: + * dataset id was incorrect + * edition was incorrect + * version was incorrect + * dimension was incorrect + * query parameters incorrect offset provided + * query parameters incorrect limit provided + 404: + description: "No dimension options were found for dimension" + 500: + $ref: '#/responses/InternalError' /instances: get: tags: @@ -600,6 +682,147 @@ paths: $ref: '#/responses/ConflictError' 500: $ref: '#/responses/InternalError' + /instances/{instance_id}/dimensions: + get: + tags: + - "Private user" + summary: "Get a list of dimensions for an instance" + description: "Get all dimensions from an instance" + parameters: + - $ref: '#/parameters/instance_id' + - $ref: '#/parameters/if_match' + produces: + - "application/json" + security: + - InternalAPIKey: [] + responses: + 200: + description: "Return a list of dimensions" + schema: + $ref: '#/definitions/Dimensions' + headers: + ETag: + type: string + description: "Defines a unique instance resource version" + 400: + $ref: '#/responses/InvalidRequestError' + 401: + $ref: '#/responses/UnauthorisedError' + 403: + $ref: '#/responses/ForbiddenError' + 404: + $ref: '#/responses/InstanceNotFound' + 409: + $ref: '#/responses/ConflictError' + 500: + $ref: '#/responses/InternalError' + patch: + tags: + - "Private" + summary: "Create one or more dimensions" + description: "Create one or more dimensions which are related to an instance" + parameters: + - $ref: '#/parameters/instance_id' + - $ref: '#/parameters/patch_dimensions' + - $ref: '#/parameters/if_match' + produces: + - "application/json-patch+json" + security: + - InternalAPIKey: [] + responses: + 200: + description: "All dimensions were successfully created" + schema: + $ref: '#/definitions/PatchDimensions' + headers: + ETag: + type: string + description: "Defines a unique instance resource version" + 400: + $ref: '#/responses/InvalidRequestError' + 404: + $ref: '#/responses/InstanceNotFound' + 409: + $ref: '#/responses/ConflictError' + 500: + $ref: '#/responses/InternalError' + + /instances/{instance_id}/dimensions/{dimension}: + put: + tags: + - "Private user" + summary: "Update dimension" + description: "Update the label and/or description of a dimension within an instance, by providing dimension name and properties to over write" + parameters: + - $ref: '#/parameters/instance_id' + - $ref: '#/parameters/dimension' + - $ref: '#/parameters/update_dimension' + - $ref: '#/parameters/if_match' + security: + - InternalAPIKey: [] + responses: + 200: + description: "The instance has been updated" + headers: + ETag: + type: string + description: "Defines a unique instance resource version" + 400: + $ref: '#/responses/InvalidRequestError' + 401: + $ref: '#/responses/UnauthorisedError' + 403: + $ref: '#/responses/ForbiddenError' + 404: + $ref: '#/responses/InstanceNotFound' + 409: + $ref: '#/responses/ConflictError' + 500: + $ref: '#/responses/InternalError' + /instances/{instance_id}/dimensions/{dimension}/options: + get: + tags: + - "Private user" + summary: "Get a list of options for a dimension" + description: "Get all unique options from a dimension. This response is designed for efficient data transfer of incredibly long lists, and as such breaks several API conventions" + parameters: + - $ref: '#/parameters/instance_id' + - $ref: '#/parameters/dimension' + - $ref: '#/parameters/if_match' + produces: + - "application/json" + security: + - InternalAPIKey: [] + responses: + 200: + description: "Return a list of unique options" + schema: + type: object + properties: + dimension: + description: "The name of the dimension" + type: string + options: + description: "A list of all unique options within a dimension" + type: array + items: + type: string + headers: + ETag: + type: string + description: "Defines a unique instance resource version" + 400: + $ref: '#/responses/InvalidRequestError' + 401: + $ref: '#/responses/UnauthorisedError' + 403: + $ref: '#/responses/ForbiddenError' + 404: + description: "dimension does not match any dimensions within the instance" + 409: + $ref: '#/responses/ConflictError' + 500: + $ref: '#/responses/InternalError' responses: ConflictError: description: "Failed to process the request due to a conflict" @@ -628,6 +851,24 @@ definitions: description: "The type of alert" example: "correction" type: string + Codelist: + type: object + properties: + href: + description: "A link to the codelist corresponding to this dimension" + type: string + id: + description: "The codelist id corresponding to this dimension" + type: string + name: + description: "The dimension name" + type: string + description: + description: "The dimension description" + type: string + label: + description: "A human readable label for dimension" + type: string CollectionID: description: "The id of the unpublished collection (of datasets) that this dataset is associated with" type: string @@ -880,6 +1121,183 @@ definitions: description: "The type of the dataset" type: string example: "cantabular_table" + DimensionCore: + description: "Core fields to disambiguate dimensions, used for embedding or as a base for the Dimension object" + type: object + properties: + code_list: + description: "A link to the code-list entry for the dimension" + type: string + identifier: + description: "The identifier of the dimension" + type: string + label: + description: "" + type: string + name: + description: "The name of the dimension" + type: string + Dimension: + description: "A single dimension within a dataset" + allOf: + - $ref: '#/definitions/DimensionCore' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + "@id": + $ref: '#/definitions/LDID' + "@type": + allOf: + - $ref: '#/definitions/LDType' + - default: "csvw:column" + description: + description: "" + type: string + is_area_type: + description: "Indicates if a dimension is an area-type (census datasets only)" + type: boolean + _links: + type: object + properties: + code_list: + description: "The code list related to this dimension" + type: object + properties: + href: + description: "A URL to the code list" + type: string + id: + description: "The unique id for the code list" + type: string + options: + $ref: '#/definitions/OptionsLink' + version: + $ref: '#/definitions/VersionLink' + self: + $ref: '#/definitions/SelfLink' + number_of_options: + description: "The number of options available for this dimension" + type: integer + variable: + description: "The variable name (census datasets only)" + type: string + Dimensions: + allOf: + - $ref: '#/definitions/ListPagination' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + items: + description: "An array of dimensions" + type: array + items: + $ref: '#/definitions/Dimension' + DimensionOptions: + allOf: + - $ref: '#/definitions/ListPagination' + - type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + items: + description: "An array of dimension options" + type: array + items: + $ref: '#/definitions/DimensionOption' + DimensionOption: + type: object + properties: + "@context": + $ref: '#/definitions/LDContext' + "@id": + $ref: '#/definitions/LDID' + dimension: + description: "The name of the dimension" + type: string + instance_id: + description: "The unique identifier for the instance in which this dimension option is associated to" + type: string + label: + description: "A label given to a dimension option" + type: string + _links: + description: "A object with all resources related to a dimension option" + type: object + properties: + code: + description: "A link to the code of the dimension for this option" + type: object + properties: + href: + description: "The url of the code that refers to the dimension for this option" + type: string + id: + description: "The id of the code that refers to the dimension for this option" + type: string + code_list: + description: "A link to the code list the dimension for this option belongs to" + type: object + properties: + href: + description: "The url of the code list that the dimension for this option belongs to" + type: string + id: + description: "The id of the code list that the dimension for this option belongs to" + type: string + version: + $ref: '#/definitions/VersionLink' + self: + $ref: '#/definitions/SelfLink' + node_id: + description: "The id of the node" + type: string + option: + description: "An option for a dimension" + type: string + PatchOptions: + description: "A list of operations to patch a dimension option. Can only handle adding values for /node_id and /order. Each element in the array is processed in sequential order." + type: array + items: + type: object + description: "Item containing all necessary information to make a single operation on the resource." + properties: + op: + description: | + The operation to be made on path. + * add - Sets the value for the provided path + type: string + enum: [add] + path: + description: "Path to value that needs to be operated on." + type: string + example: "/node_id" + enum: [/node_id, /order] + value: + description: "A value that will be set for the provided path. /node_id accepts string values, and /order accepts integer values." + example: "node_123" + PatchDimensions: + description: "A list of operations to patch dimensions. Can only handle adding lists of dimension values, and modifying order and node_id values for existing dimension options. The patch operations are executed in bulk to improve performance, and they are idempotent. If at least one of the provided dimensions and/or options in a patch path cannot be matched against existing dimension options, the request will fail with 404." + type: array + items: + type: object + description: "Item containing all necessary information to make a single operation on the resource." + properties: + op: + description: | + The operation to be made on path. + * add - Sets the value for the provided path + type: string + enum: ["add"] + path: + description: "Path to value that needs to be operated on." + type: string + example: "/-" + enum: ["/-", "/{dimension}/options/{option}/order", "/{dimension}/options/{option}/node_id"] + value: + description: "A list of dimenions that will be added to the instance." + example: "[{\"dimension\": \"dim1\", \"option\": \"op1\"}, {\"dimension\": \"dim1\", \"option\": \"op2\"}, {\"op\": \"add\", \"path\": \"/dim1/options/op1/order\", \"value\": 3}, {\"op\": \"add\", \"path\": \"/dim1/options/op2/node_id\", \"value\": \"node123\"}]" CSVDownload: description: "Additional fields available for CSV downloads" type: object @@ -964,7 +1382,6 @@ definitions: format: uri state: $ref: '#/definitions/State' - Editions: type: object allOf: @@ -1267,9 +1684,7 @@ definitions: $ref: '#/definitions/State' Version: description: "An object containing information about published datasets from the ONS" - required: [ - release_date, - ] + required: [release_date] allOf: - $ref: '#/definitions/dcatSeriesFull' - $ref: '#/definitions/dcatVersionFull' @@ -1285,6 +1700,10 @@ definitions: type: string is_based_on: $ref: '#/definitions/IsBasedOn' + _embedded: + type: array + items: + $ref: '#/definitions/DimensionCore' _links: $ref: '#/definitions/VersionLinks' type: @@ -1450,6 +1869,13 @@ definitions: id: description: "The unique id for the latest version of a dataset" type: "string" + OptionsLink: + description: "A list of links related to this dimension" + type: object + properties: + href: + description: "A URL to a list of options for this dimension" + type: string SelfLink: description: "A link to this resource" readOnly: true From 076e2d70abd9323c5c428da8278888bc8e92f8f6 Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 31 Oct 2023 15:59:06 +0000 Subject: [PATCH 8/9] Fix errors and begin to better structure definitions with 'links' --- swagger.yaml | 179 +++++++++++++++++---------------------------------- 1 file changed, 60 insertions(+), 119 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 6e07ed14..2ac24c1b 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -121,6 +121,13 @@ parameters: required: true schema: $ref: "#/definitions/Dataset" + update_dimension: + name: dimension + description: "A dimension object to update for a given instance" + in: body + required: true + schema: + $ref: '#/definitions/Dimension' version: name: version description: "A version of a dataset" @@ -133,7 +140,7 @@ parameters: in: body required: true schema: - $ref: '#/definitions/UpdateVersion' + $ref: '#/definitions/Version' limit: name: limit description: "Maximum number of items that will be returned. A value of zero will return zero items. The default value is 20, and the maximum limit allowed is 1000" @@ -175,11 +182,6 @@ securityDefinitions: description: "API key used to allow only internal services to update the state of an import job" in: header type: apiKey - DownloadServiceAPIKey: - name: x-download-service-token - description: "API key used to allow the download service to access public and private links to a download" - in: header - type: apiKey paths: /datasets: get: @@ -261,6 +263,8 @@ paths: responses: 200: description: "A json object for a single Dataset" + schema: + $ref: '#/definitions/UpdateDatasetResponse' 400: description: "Bad Request due to invalid json in the request body" 401: @@ -837,20 +841,6 @@ responses: UnauthorisedError: description: "The token provided is unauthorised to carry out this operation" definitions: - Alert: - description: "Important information relating to a version of a dataset" - type: object - properties: - date: - description: "The date and time of when an alert took place" - type: string - description: - description: "Detail of what a user needs to be aware of for this dataset" - type: string - type: - description: "The type of alert" - example: "correction" - type: string Codelist: type: object properties: @@ -1027,7 +1017,7 @@ definitions: is_based_on: $ref: '#/definitions/IsBasedOn' _links: - $ref: '#/definitions/DatasetListLinks' + $ref: '#/links/DatasetListLinks' national_statistic: description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" type: boolean @@ -1093,7 +1083,7 @@ definitions: is_based_on: $ref: '#/definitions/IsBasedOn' _links: - $ref: '#/definitions/DatasetLinks' + $ref: '#/links/DatasetLinks' national_statistic: description: "The flag indicating the resource is a national statistic. These are certified as compliant with the Code of Practice for Official Statistics" type: boolean @@ -1171,11 +1161,11 @@ definitions: description: "The unique id for the code list" type: string options: - $ref: '#/definitions/OptionsLink' + $ref: '#/links/Options' version: - $ref: '#/definitions/VersionLink' + $ref: '#/links/Version' self: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' number_of_options: description: "The number of options available for this dimension" type: integer @@ -1247,9 +1237,9 @@ definitions: description: "The id of the code list that the dimension for this option belongs to" type: string version: - $ref: '#/definitions/VersionLink' + $ref: '#/links/Version' self: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' node_id: description: "The id of the node" type: string @@ -1371,7 +1361,7 @@ definitions: is_based_on: $ref: '#/definitions/IsBasedOn' _links: - $ref: '#/definitions/EditionLinks' + $ref: '#/links/EditionLinks' type: $ref: '#/definitions/Type' next_edition: @@ -1405,7 +1395,7 @@ definitions: "@type": $ref: '#/definitions/LDType' _links: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' state: $ref: '#/definitions/State' Event: @@ -1449,7 +1439,7 @@ definitions: type: string _links: allOf: - - $ref: '#/definitions/VersionLinks' + - $ref: '#/links/VersionLinks' - type: object properties: version: @@ -1460,7 +1450,7 @@ definitions: href: type: string job: - $ref: '#/definitions/JobLink' + $ref: '#/links/Job' state: $ref: '#/definitions/State' Instances: @@ -1472,43 +1462,12 @@ definitions: items: $ref: '#/definitions/Instance' _links: - $ref: '#/definitions/ListLinks' - LatestChange: - description: "A single change between this version and the previous version of an edition for a dataset" - type: object - properties: - description: - description: "A description of what has changed between versions" - type: string - name: - description: "The name of the change that has occurred between versions" - type: string - example: "changes in classification" - type: - description: "The type of change" - type: string - example: "summary of changes" - ListLinks: - description: "The _links structure provided on all list endpoints" - type: object - properties: - self: - $ref: '#/definitions/SelfLink' - next: - type: object - properties: - href: - type: string - prev: - type: object - properties: - href: - type: string + $ref: '#/links/ListLinks' ListPagination: description: "The fields required on a list endpoint to facilitate pagination" properties: _links: - $ref: '#/definitions/ListLinks' + $ref: '#/links/ListLinks' count: description: "The number of versions returned for an edition of a dataset" readOnly: true @@ -1614,21 +1573,6 @@ definitions: format: url sub_property_of: type: string - Temporal: - description: "A list of frequencies the dataset covers for a particular period of time" - type: array - items: - type: object - properties: - start_date: - description: "The start date of the time period in which the version of the dataset covers this frequency" - type: string - end_date: - description: "The end date of the time period in which the version of the dataset covers this frequency" - type: string - frequency: - description: "The time frequency the version of the dataset covers for the period of time between start_date and end_date" - type: string UpdateDatasetResponse: description: "A model for the response body when creating a new dataset" type: object @@ -1651,11 +1595,6 @@ definitions: collection_id: $ref: '#/definitions/CollectionID' - $ref: "#/definitions/Dataset" - UpdateVersion: - description: "An object containing information to be updated on a version resource" - type: object - properties: - $ref: '#/definitions/Version' Versions: allOf: - $ref: '#/definitions/ListPagination' @@ -1679,7 +1618,7 @@ definitions: "@type": $ref: '#/definitions/LDType' _links: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' state: $ref: '#/definitions/State' Version: @@ -1705,7 +1644,7 @@ definitions: items: $ref: '#/definitions/DimensionCore' _links: - $ref: '#/definitions/VersionLinks' + $ref: '#/links/VersionLinks' type: $ref: '#/definitions/Type' next_version: @@ -1718,8 +1657,7 @@ definitions: readOnly: true state: $ref: '#/definitions/State' - - # Link objects +links: DatasetLinks: description: "A list of links related to this resource" type: object @@ -1733,24 +1671,24 @@ definitions: example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions" type: string latest_version: - $ref: '#/definitions/LatestVersionLink' + $ref: '#/links/LatestVersion' self: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' DatasetListLinks: description: "A list of links related to this resource, in the context of a list of datasets" type: object properties: latest_version: - $ref: '#/definitions/LatestVersionLink' + $ref: '#/links/LatestVersion' self: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' EditionLinks: description: "A list of links related to this resource" readOnly: true type: object properties: dataset: - $ref: '#/definitions/DatasetLink' + $ref: '#/links/Dataset' editions: readOnly: true type: object @@ -1760,14 +1698,14 @@ definitions: example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions" type: string latest_version: - $ref: '#/definitions/LatestVersionLink' + $ref: '#/links/LatestVersion' self: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' versions: type: object properties: href: - description: "A URL to all versions dor an edition of a dataset" + description: "A URL to all versions for an edition of a dataset" example: "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/edition/2017/versions" type: string next: @@ -1792,11 +1730,11 @@ definitions: readOnly: true properties: dataset: - $ref: '#/definitions/DatasetLink' + $ref: '#/links/Dataset' edition: - $ref: '#/definitions/EditionLink' + $ref: '#/links/Edition' self: - $ref: '#/definitions/SelfLink' + $ref: '#/links/Self' versions: type: object properties: @@ -1820,7 +1758,23 @@ definitions: format: url id: type: string - DatasetLink: + ListLinks: + description: "The _links structure provided on all list endpoints" + type: object + properties: + self: + $ref: '#/links/Self' + next: + type: object + properties: + href: + type: string + prev: + type: object + properties: + href: + type: string + Dataset: description: "An object containing the dataset id and link" readOnly: true type: object @@ -1832,7 +1786,7 @@ definitions: id: description: "The unique id for the dataset of this version" type: string - EditionLink: + Edition: description: "An object containing the edition and link" readOnly: true type: object @@ -1844,7 +1798,7 @@ definitions: id: description: "The unique id for the dataset edition for a version" type: string - JobLink: + Job: description: "An object describing the ID and URL of the job containing this instance" required: ["id", "href"] type: object @@ -1857,7 +1811,7 @@ definitions: description: "The ID of the job containing this instance" example: 042e216a-7822-4fa0-a3d6-e3f5248ffc35 type: string - LatestVersionLink: + LatestVersion: description: "An object containing the latest version id and link" type: object readOnly: true @@ -1869,14 +1823,14 @@ definitions: id: description: "The unique id for the latest version of a dataset" type: "string" - OptionsLink: + Options: description: "A list of links related to this dimension" type: object properties: href: description: "A URL to a list of options for this dimension" type: string - SelfLink: + Self: description: "A link to this resource" readOnly: true type: object @@ -1884,20 +1838,7 @@ definitions: href: description: "A URL to this resource" type: string - SpatialLink: - type: object - properties: - href: - description: "A url to a list of geography ranges for the version of the dataset" - type: string - TaxonomyLink: - description: "A link to the taxonomy of the dataset" - type: object - properties: - href: - description: "A url to the taxonomy of the dataset" - type: string - VersionLink: + Version: description: "The dataset version this resource belongs to" type: object properties: From a9132f1f15cc6b43a35a0c6db300d2342c60c5aa Mon Sep 17 00:00:00 2001 From: Eleanor Deal Date: Tue, 31 Oct 2023 16:05:06 +0000 Subject: [PATCH 9/9] Reintroduce /options PATCH request in spec --- swagger.yaml | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/swagger.yaml b/swagger.yaml index 2ac24c1b..ecc241b5 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -109,6 +109,12 @@ parameters: required: true schema: $ref: '#/definitions/NewInstance' + option: + name: option + description: "A option to set within a type" + in: path + required: true + type: string state: name: "state" description: "A comma separated list of state values to filter on (e.g. ‘completed,edition-confirmed’)" @@ -827,6 +833,44 @@ paths: $ref: '#/responses/ConflictError' 500: $ref: '#/responses/InternalError' + /instances/{instance_id}/dimensions/{dimension}/options/{option}: + patch: + tags: + - "Private" + summary: "Modify a dimension option for an instance" + description: | + Modify a dimension option for an instance by setting values for node_id or order + parameters: + - $ref: '#/parameters/instance_id' + - $ref: '#/parameters/dimension' + - $ref: '#/parameters/option' + - $ref: '#/parameters/patch_options' + - $ref: '#/parameters/if_match' + produces: + - "application/json-patch+json" + security: + - InternalAPIKey: [] + responses: + 200: + description: "The dimension option was modified and the successfully applied patch operations are returned" + schema: + $ref: '#/definitions/PatchOptions' + headers: + ETag: + type: string + description: "Defines a unique instance resource version" + 400: + $ref: '#/responses/InvalidRequestError' + 401: + $ref: '#/responses/UnauthorisedError' + 403: + $ref: '#/responses/ForbiddenError' + 404: + description: "InstanceId does not match any instances" + 409: + $ref: '#/responses/ConflictError' + 500: + $ref: '#/responses/InternalError' responses: ConflictError: description: "Failed to process the request due to a conflict"