swagger: '2.0' info: version: 0.0.0 title: API information description: > # API information ## CRUD operations We do our best to have all our URLs be [RESTful](http://en.wikipedia.org/wiki/Representational_state_transfer). Every endpoint (URL) may support one of five different http verbs. GET requests fetch information about an object, POST requests create objects. PATCH [JSON Merge Patch](https://tools.ietf.org/html/rfc7396) requests perform partial updates. ## Structure ### The envelope Every response is contained by an envelope. That is, each response has a predictable set of keys with which you can expect to interact: ```json { "warnings": [ ... ], "data": { ... }, "dictionaries": { ... }, "errors": [ ... ] } ``` #### ERRORS Error messages corresponding to functional blocking issues encountered when processing an operation. When at least one message has a level 'error' nothing has been processed so no 'data' are returned. In this case the HTTP status become 200 for POST (instead of 201) and DELETE (instead of 204). #### WARNINGS Warning messages corresponding to non blocking issues encountered when processing an operation. #### DATA The data key is the meat of the response. It contains all information regarding the resource requested. #### DICTIONARIES Each dictionary contains: - localized data: it's possible to request for a specific code (e.g. location code) the translation in the language code specified as query parameter. The translation applies as well to the related information: in case of location code, type of location (country or city), corresponding city, state, country, etc. - dictionarized data: information used on different parts of the message can be defined once and referenced via an ID. It that case, the id makes the connection between dictionary and data information ### Example of request/response When triggering an API operation it is interesting to evaluate the response (or the data model corresponding to the input body in case of POST). ``` GET /carts/{cartId}/product/{productId} HTTP/1.1 Accept: application/json ``` Multiple errors can occur in response to a single request. The list of error messages is provided by the server: ```json HTTP/1.1 400 Bad Request Content-Type: application/json { "errors": [ { "code": "04926", "source": { "pointer": "/names/0/lastName" }, "title": "INVALID DATA RECEIVED" "detail": "must match \"^[A-Za-zÀ-ÿ][A-Za-zÀ-ÿ -.]{1,69}$\" }, { "code": "36986", "source": { "pointer": "/0/dateOfBirth" }, "detail": "Date of birth '2042-07-01' should be in the past", "title": "INVALID DATA RECEIVED" }, ] } ``` Note: example added for illustration only. A few considerations on the error message structure: - The title communicates the type of problem encountered. - The code refers to an application-specific code representing the type of problem encountered. Code and title have a similar behaviour, since they communicate which is the problem type. However, it is suggested to rely on the code as a unique identifier. - The detail is used to provide information specific to this occurrence of the problem. Message may use source to point to the top-level of the document (""). The source member can also be used to indicate that the error originated from a problem with a URI query parameter (parameter field used instead of pointer in that case). Standard [HTTP response status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) apply. As such they are not all mentioned below. ## Miscellaneous ### Temporary id (tid) A temporary id (``tid``) can be used to: - identify an object in the request of a POST operation when the id of the object is not known yet. - identify an object in the response of a PUT operation when the id of the object is changing. In all cases, a tid is only valid for the time of the transaction ### Output filtering JSON output can be filtered using ``-fields`` and ``fields`` query parameters, followed by the fully qualified name of the attribute to filter/keep. Optionally the ``keepRequiredFields`` boolean query parameter can be used to avoid filtering required fields out. Examples: ``` GET /carts/{cartId}?-fields=data.products ``` will filter all products out of the response ``` GET /carts/{cartId}?fields=data.products.price ``` will keep only the price of the products in response Any questions, suggestions or feedbacks, thank you for contacting the API team ### Traceability token For better traceability of requests, a traceability token can and should be added to every call to the API. This token is composed of both a session part and a request part resulting in a unique ID for a single request. This opens the door for: - Easy retrieval of information regarding that request. - Linking the request to other requests performed in the same user session. This traceability token is materialized by an ``Ama-Client-Ref`` header to be sent in each and every request. This header must be formatted as following: ``${SESSION_ID}:${REQUEST_ID}``. Where: - ``SESSION_ID``: is a client-side generated token identifying the client-side user session matching following regular expression ``[a-zA-Z0-9-]{10,48}``. A recommended way is to implement it as an [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) in [RFC 4122](https://tools.ietf.org/html/rfc4122) format. - For example: ``123e4567-e89b-12d3-a456-426655440000`` - ``REQUEST_ID`` is a client-side request id within the client-side user session matching the ``[a-zA-Z0-9]{1,10}`` format. - For example: ``1``, ``42``, ``5fa2``, ``Px2z5``, ... - There is no notion of order between two ``REQUEST_ID`` - ``REQUEST_ID`` must be unique within a session. Examples: - Request ``2fc0`` within session ``123e4567-e89b-12d3-a456-426655440000`` traceability token: ``Ama-Client-Ref: 123e4567-e89b-12d3-a456-426655440000:2fc0`` - Request ``7ba19e`` within session ``123e4567-e89b-12d3-a456-426655440000`` traceability token: ``Ama-Client-Ref: 123e4567-e89b-12d3-a456-426655440000:7ba19e`` contact: email: noreply@<%= name %>.com host: your.api.endpoint.com basePath: /v2 schemes: - https consumes: - application/json produces: - application/json