diff --git a/doc/API_documentation/v3/_HowTo_Swagger.md b/doc/API_documentation/v3/_HowTo_Swagger.md index e0f8b2b779..85d153ef1f 100644 --- a/doc/API_documentation/v3/_HowTo_Swagger.md +++ b/doc/API_documentation/v3/_HowTo_Swagger.md @@ -1,9 +1,11 @@ # How to update the documentation in swaggerhub : -The doc is composed of 3 files +The doc is composed of many files - `api.yaml` (main file) -- `responses.yaml` - `schemas.yaml` +- `common.yaml` +- `record.yaml` +- ... to update in swaggerhub (single file) : - install swagger-cli diff --git a/doc/API_documentation/v3/_compiled.yaml b/doc/API_documentation/v3/_compiled.yaml index 892d981a73..95ab6812dd 100644 --- a/doc/API_documentation/v3/_compiled.yaml +++ b/doc/API_documentation/v3/_compiled.yaml @@ -143,7 +143,291 @@ paths: To get smaller / faster response, facets and stories children are ommited by default. - Add _include_ parameters to get those if needed. + Add __include__ parameters to get those if needed. + + each __include__ parameter maps a matching sub-object in the response data. + + Since records and stories results are dispatched into 2 separated arrays `response.results.records[]` or + `response.results.stories[]` (depending on the `search_type=0|1` parameter), one must use the correct __include(s)__ + that match the result structure. + + ### facets + ``` + { + "response": { + "facets": [ + { + "name": "_base", + "field": "database", + "values": [ + { + "value": "Base Beta Version 3.0", + "raw_value": "Base Beta Version 3.0", + "count": 2902, + "query": "database:\"Base Beta Version 3.0\"" + }, + { + "value": "Base test demo support", + "raw_value": "Base test demo support", + "count": 1120, + "query": "database:\"Base test demo support\"" + }, + ... + ] + }, + { + "name": "Categorie", + "field": "field.Categorie", + "values": [ + { + "value": "USA Août 2018", + "raw_value": "USA Août 2018", + "count": 268, + "query": "field.Categorie=\"USA Août 2018\"" + }, + { + "value": "Voyage Bahamas", + "raw_value": "Voyage Bahamas", + "count": 83, + "query": "field.Categorie=\"Voyage Bahamas\"" + }, + ... + ] + }, + { + "name": "MotsCles", + "field": "field.MotsCles", + "values": [ + { + "value": "USA", + "raw_value": "USA", + "count": 914, + "query": "field.MotsCles=\"USA\"" + }, + ... + ] + }, + ... + ] + } + } + ``` + + ### suggestions + flatened facets + ``` + "response": { + "suggestions": [ + { + "suggestion": "Demo Online", + "query": "collection:\"Demo Online\"", + "hits": 2 + }, + { + "suggestion": "Voyage Bahamas", + "query": "field.Categorie=\"Voyage Bahamas\"", + "hits": 83 + }, + ... + ] + } + ``` + + ### results.records.subdefs ; results.stories.subdefs + ``` + "response": { + "results": { + "records": [ + { + "subdefs": [ + { + "name": "document", + "permalink": { + "created_on": "2021-09-23T16:04:25+02:00", + "id": 12539, + "is_activated": false, + "label": "TX9329_23", + "updated_on": "2021-09-23T16:05:34+02:00", + "page_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/?token=xxx", + "download_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/TX9329_23.tif?token=xxx&download=1", + "url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/TX9329_23.tif?token=xxx" + }, + "height": 3181, + "width": 3181, + "filesize": 30439108, + "devices": [ + "all" + ], + "player_type": "UNKNOWN", + "mime_type": "image/tiff", + "substituted": false, + "created_on": "2021-09-23T16:04:25+02:00", + "updated_on": "2021-09-23T16:04:25+02:00", + "url": "https://demo.alchemyasp.com/medias/xxxx.yyyy.zzzz", + "url_ttl": 7200 + }, + { + "name": "preview", + "permalink": { + "created_on": "2021-09-23T16:04:46+02:00", + "id": 12541, + "is_activated": false, + "label": "TX9329_23", + "updated_on": "2021-09-23T16:05:34+02:00", + "page_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/?token=xxx", + "download_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/TX9329_23.jpg?token=xxx&download=1", + "url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/TX9329_23.jpg?token=xxx" + }, + "height": 800, + "width": 800, + "filesize": 112906, + "devices": [ + "screen" + ], + "player_type": "IMAGE", + "mime_type": "image/jpeg", + "substituted": false, + "created_on": "2021-09-23T16:04:46+02:00", + "updated_on": "2021-09-23T16:04:46+02:00", + "url": "https://demo.alchemyasp.com/medias/xxxx.yyyy.zzzz", + "url_ttl": 7200 + }, + ... + ] + } + ] + } + } + ``` + + ### results.records.caption ; results.stories.caption + simple metadata + ``` + "response": { + "results": { + "records": [ + { + "caption": [ + { + "meta_structure_id": 12, + "name": "Titre", + "value": "New demo pictures - Oceans" + }, + { + "meta_structure_id": 4, + "name": "MotsCles", + "value": "Bahamas ; mer ; Nassau ; plage ; nuage ; turquoise ; ocean ; sea ; Atlantic" + }, + ... + ] + } + ] + } + } + ``` + + ### results.records.metadata ; results.stories.metadata + complete metadata with labels + ``` + { + "response": { + "results": { + "records": [ + { + "metadata": [ + { + "meta_structure_id": 12, + "name": "Titre", + "labels": { + "fr": "Titre principal", + "en": "Headline title", + "de": "Titre", + "nl": "Titre" + }, + "meta_id": 346744, + "value": "New demo pictures - Oceans" + }, + { + "meta_structure_id": 4, + "name": "MotsCles", + "labels": { + "fr": "Mots Clés", + "en": "Keywords", + "de": "MotsCles", + "nl": "MotsCles" + }, + "meta_id": 346745, + "value": "Bahamas" + }, + ... + ] + } + ] + } + } + } + ``` + + ### results.records.status ; results.stories.status + ``` + "response": { + "results": { + "records": [ + { + "status": [ + { + "bit": 8, + "state": false + }, + { + "bit": 9, + "state": true + }, + ... + ] + } + ] + } + } + ``` + + ### results.records.thumbnail ; results.stories.thumbnail + always included + + ### results.records.technical_informations + always included + + _nb:_ since stories are not related to a document, there is no technical_informations for stories. + + ### results.records.children + In story search mode, will publish a children[] array for each result. See _story_children_limit_ parameter. + + children is an array of records, with same structure as a result record. + ``` + "response": { + "results": { + "stories": [ + { + "children": [ + { + // record structure + }, + ... + ], + ... + }, + ... + ] + } + } + ``` + ### results.records.children.thumbnail + ### results.records.children.technical_informations + ### results.records.children.subdefs + ### results.records.children.caption + ### results.records.children.metadata + ### results.records.children.status + see result.records.* includes. parameters: - name: query in: query @@ -378,6 +662,13 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + story_id: + type: integer + example: 1400 + cover_record_id: + type: integer + description: id of the record chosen as "cover" (or null) + example: 55 mime_type: type: string default: null @@ -511,6 +802,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -647,6 +941,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -850,8 +1147,10 @@ paths: properties: record_id: type: integer + example: 555 collection_id: type: integer + example: 123 uuid: type: string example: dcee40ea-ee26-4d8b-b0c2-d61305b03bc0 @@ -869,6 +1168,10 @@ paths: type: type: string example: image + cover_record_id: + type: integer + description: 'for a story, id of the record chosen as "cover" (or null)' + example: null created_on: type: string format: date-time @@ -879,6 +1182,7 @@ paths: example: '2021-01-01 15:30:00' coll_id: type: integer + example: '123' collection_name: type: string example: collection de test @@ -1196,6 +1500,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -1364,6 +1671,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -2053,6 +2363,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -2409,6 +2722,13 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + story_id: + type: integer + example: 1400 + cover_record_id: + type: integer + description: id of the record chosen as "cover" (or null) + example: 55 mime_type: type: string default: null @@ -2542,6 +2862,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -2710,6 +3033,13 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + story_id: + type: integer + example: 1400 + cover_record_id: + type: integer + description: id of the record chosen as "cover" (or null) + example: 55 mime_type: type: string default: null @@ -2843,6 +3173,9 @@ paths: example: 5b079f33-0851-4aec-a978-b7f8d7204e5a - type: object properties: + record_id: + type: integer + example: 34 mime_type: type: string example: image/jpeg @@ -3000,7 +3333,7 @@ paths: tags: - story summary: Returns uri of each record (child) contained in the story ; Optional pagination - description: Returns children of a story + description: Returns children of a story. operationId: getStoryChildren parameters: - name: sbas_id diff --git a/doc/API_documentation/v3/api.yaml b/doc/API_documentation/v3/api.yaml index d953a93ac6..b75993e8f5 100644 --- a/doc/API_documentation/v3/api.yaml +++ b/doc/API_documentation/v3/api.yaml @@ -175,7 +175,291 @@ paths: To get smaller / faster response, facets and stories children are ommited by default. - Add _include_ parameters to get those if needed. + Add __include__ parameters to get those if needed. + + each __include__ parameter maps a matching sub-object in the response data. + + Since records and stories results are dispatched into 2 separated arrays `response.results.records[]` or + `response.results.stories[]` (depending on the `search_type=0|1` parameter), one must use the correct __include(s)__ + that match the result structure. + + ### facets + ``` + { + "response": { + "facets": [ + { + "name": "_base", + "field": "database", + "values": [ + { + "value": "Base Beta Version 3.0", + "raw_value": "Base Beta Version 3.0", + "count": 2902, + "query": "database:\"Base Beta Version 3.0\"" + }, + { + "value": "Base test demo support", + "raw_value": "Base test demo support", + "count": 1120, + "query": "database:\"Base test demo support\"" + }, + ... + ] + }, + { + "name": "Categorie", + "field": "field.Categorie", + "values": [ + { + "value": "USA Août 2018", + "raw_value": "USA Août 2018", + "count": 268, + "query": "field.Categorie=\"USA Août 2018\"" + }, + { + "value": "Voyage Bahamas", + "raw_value": "Voyage Bahamas", + "count": 83, + "query": "field.Categorie=\"Voyage Bahamas\"" + }, + ... + ] + }, + { + "name": "MotsCles", + "field": "field.MotsCles", + "values": [ + { + "value": "USA", + "raw_value": "USA", + "count": 914, + "query": "field.MotsCles=\"USA\"" + }, + ... + ] + }, + ... + ] + } + } + ``` + + ### suggestions + flatened facets + ``` + "response": { + "suggestions": [ + { + "suggestion": "Demo Online", + "query": "collection:\"Demo Online\"", + "hits": 2 + }, + { + "suggestion": "Voyage Bahamas", + "query": "field.Categorie=\"Voyage Bahamas\"", + "hits": 83 + }, + ... + ] + } + ``` + + ### results.records.subdefs ; results.stories.subdefs + ``` + "response": { + "results": { + "records": [ + { + "subdefs": [ + { + "name": "document", + "permalink": { + "created_on": "2021-09-23T16:04:25+02:00", + "id": 12539, + "is_activated": false, + "label": "TX9329_23", + "updated_on": "2021-09-23T16:05:34+02:00", + "page_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/?token=xxx", + "download_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/TX9329_23.tif?token=xxx&download=1", + "url": "https://demo.alchemyasp.com/permalink/v1/43/82227/document/TX9329_23.tif?token=xxx" + }, + "height": 3181, + "width": 3181, + "filesize": 30439108, + "devices": [ + "all" + ], + "player_type": "UNKNOWN", + "mime_type": "image/tiff", + "substituted": false, + "created_on": "2021-09-23T16:04:25+02:00", + "updated_on": "2021-09-23T16:04:25+02:00", + "url": "https://demo.alchemyasp.com/medias/xxxx.yyyy.zzzz", + "url_ttl": 7200 + }, + { + "name": "preview", + "permalink": { + "created_on": "2021-09-23T16:04:46+02:00", + "id": 12541, + "is_activated": false, + "label": "TX9329_23", + "updated_on": "2021-09-23T16:05:34+02:00", + "page_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/?token=xxx", + "download_url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/TX9329_23.jpg?token=xxx&download=1", + "url": "https://demo.alchemyasp.com/permalink/v1/43/82227/preview/TX9329_23.jpg?token=xxx" + }, + "height": 800, + "width": 800, + "filesize": 112906, + "devices": [ + "screen" + ], + "player_type": "IMAGE", + "mime_type": "image/jpeg", + "substituted": false, + "created_on": "2021-09-23T16:04:46+02:00", + "updated_on": "2021-09-23T16:04:46+02:00", + "url": "https://demo.alchemyasp.com/medias/xxxx.yyyy.zzzz", + "url_ttl": 7200 + }, + ... + ] + } + ] + } + } + ``` + + ### results.records.caption ; results.stories.caption + simple metadata + ``` + "response": { + "results": { + "records": [ + { + "caption": [ + { + "meta_structure_id": 12, + "name": "Titre", + "value": "New demo pictures - Oceans" + }, + { + "meta_structure_id": 4, + "name": "MotsCles", + "value": "Bahamas ; mer ; Nassau ; plage ; nuage ; turquoise ; ocean ; sea ; Atlantic" + }, + ... + ] + } + ] + } + } + ``` + + ### results.records.metadata ; results.stories.metadata + complete metadata with labels + ``` + { + "response": { + "results": { + "records": [ + { + "metadata": [ + { + "meta_structure_id": 12, + "name": "Titre", + "labels": { + "fr": "Titre principal", + "en": "Headline title", + "de": "Titre", + "nl": "Titre" + }, + "meta_id": 346744, + "value": "New demo pictures - Oceans" + }, + { + "meta_structure_id": 4, + "name": "MotsCles", + "labels": { + "fr": "Mots Clés", + "en": "Keywords", + "de": "MotsCles", + "nl": "MotsCles" + }, + "meta_id": 346745, + "value": "Bahamas" + }, + ... + ] + } + ] + } + } + } + ``` + + ### results.records.status ; results.stories.status + ``` + "response": { + "results": { + "records": [ + { + "status": [ + { + "bit": 8, + "state": false + }, + { + "bit": 9, + "state": true + }, + ... + ] + } + ] + } + } + ``` + + ### results.records.thumbnail ; results.stories.thumbnail + always included + + ### results.records.technical_informations + always included + + _nb:_ since stories are not related to a document, there is no technical_informations for stories. + + ### results.records.children + In story search mode, will publish a children[] array for each result. See _story_children_limit_ parameter. + + children is an array of records, with same structure as a result record. + ``` + "response": { + "results": { + "stories": [ + { + "children": [ + { + // record structure + }, + ... + ], + ... + }, + ... + ] + } + } + ``` + ### results.records.children.thumbnail + ### results.records.children.technical_informations + ### results.records.children.subdefs + ### results.records.children.caption + ### results.records.children.metadata + ### results.records.children.status + see result.records.* includes. parameters: - $ref: '#/components/parameters/query' @@ -735,7 +1019,7 @@ paths: tags: - story summary: Returns uri of each record (child) contained in the story ; Optional pagination - description: Returns children of a story + description: Returns children of a story. operationId: getStoryChildren parameters: - $ref: '#/components/parameters/sbas_id' diff --git a/doc/API_documentation/v3/es.yaml b/doc/API_documentation/v3/es.yaml index 0858e5fe9f..ada0bb94f8 100644 --- a/doc/API_documentation/v3/es.yaml +++ b/doc/API_documentation/v3/es.yaml @@ -35,8 +35,10 @@ ESRecordSource: properties: record_id: $ref: 'common.yaml#/ID' + example: 555 collection_id: $ref: 'common.yaml#/ID' + example: 123 uuid: type: string example: @@ -59,6 +61,10 @@ ESRecordSource: type: string example: 'image' + cover_record_id: + $ref: 'common.yaml#/ID' + description: 'for a story, id of the record chosen as "cover" (or null)' + example: null created_on: type: string format: date-time @@ -71,18 +77,17 @@ ESRecordSource: '2021-01-01 15:30:00' coll_id: $ref: 'common.yaml#/ID' + example: '123' collection_name: type: string example: 'collection de test' witdh: type: integer - example: - 5616 + example: 5616 height: type: integer - example: - 3744 + example: 3744 size: type: integer example: diff --git a/doc/API_documentation/v3/record.yaml b/doc/API_documentation/v3/record.yaml index f121c7cc46..14b2915d7d 100644 --- a/doc/API_documentation/v3/record.yaml +++ b/doc/API_documentation/v3/record.yaml @@ -83,6 +83,10 @@ - $ref: '#/_Record_' - type: object properties: + record_id: + type: integer + example: + 34 mime_type: type: string example: @@ -134,6 +138,14 @@ - $ref: '#/_Record_' - type: object properties: + story_id: + type: integer + example: + 1400 + cover_record_id: + $ref: 'common.yaml#/ID' + description: 'id of the record chosen as "cover" (or null)' + example: 55 mime_type: type: string default: null