Emporix Regions API

openapi: 3.2.0
info:
  title: Emporix Regions API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Regions across 2 of this provider''s published API definitions: emporix-country-service-openapi.yml, emporix-country-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2:
  - country.country_manage
tags:
- name: Regions
paths:
  /country/{tenant}/regions:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    get:
      summary: Get all regions
      description: Get the filtered list of regions. The endpoint fully supports paging, sorting and filtering mechanism.
      security:
      - OAuth2: []
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
      - $ref: '#/components/parameters/trait_paged_pageNumber'
      - $ref: '#/components/parameters/trait_paged_pageSize'
      - $ref: '#/components/parameters/trait_XTotalCount_header'
      - $ref: '#/components/parameters/trait_sort'
      - $ref: '#/components/parameters/trait_region_name_query_param'
      - $ref: '#/components/parameters/trait_region_code_query_param'
      responses:
        '200':
          $ref: '#/components/responses/GetRegions'
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      operationId: GET-country-list-all-regions
      tags:
      - Regions
    servers:
    - url: https://api.emporix.io
  /country/{tenant}/regions/{regionCode}:
    parameters:
    - $ref: '#/components/parameters/trait_tenant'
    - $ref: '#/components/parameters/trait_region_code_path'
    get:
      summary: Retrieving a region
      description: Retrieves a region by the specified code.
      security:
      - OAuth2: []
      responses:
        '200':
          $ref: '#/components/responses/GetRegion'
        '400':
          $ref: '#/components/responses/BadRequest_400'
        '404':
          $ref: '#/components/responses/NotFound_404'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
      operationId: GET-country-retrieve-region
      tags:
      - Regions
      parameters:
      - $ref: '#/components/parameters/trait_acceptLanguage_header'
    servers:
    - url: https://api.emporix.io
components:
  parameters:
    trait_paged_pageNumber:
      name: pageNumber
      in: query
      description: 'The page number to be retrieved where the size of the pages must be specified by the pageSize parameter.

        The number of the first page is 1.

        '
      schema:
        default: 1
        minimum: 1
        type: integer
    trait_XTotalCount_header:
      in: header
      name: X-Total-Count
      required: false
      description: In order to get information how many entities meet a filter requirements, X-Total-Count header has been introduced. The header is optional and its default value is false. It the header is provided and it is true then total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). In other words, the information about total count is returned on demand, depending of an existence of X-Total-Count header in a request. Therefore, the X-Total-Count header is not returned if an API consumer didn’t ask for it.
      schema:
        default: false
        type: boolean
    trait_region_code_path:
      name: regionCode
      in: path
      required: true
      schema:
        type: string
      description: The region code.
    trait_acceptLanguage_header:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
        example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
      description: 'List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

        * If the header is set to a particular language or a list of languages, all localized fields are retrieved as maps with the first matched language only.

        * If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.

        * If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.

        '
    trait_region_code_query_param:
      name: code
      in: query
      required: false
      schema:
        type: string
      description: 'Region codes. When specified, only regions containing the specified codes are returned.


        **Note**: When filtering the results with this field, the `contains` operator is used.

        '
    trait_paged_pageSize:
      name: pageSize
      in: query
      description: 'The number of documents being retrieved on the page.

        '
      schema:
        default: 60
        minimum: 1
        type: integer
    trait_sort:
      in: query
      name: sort
      required: false
      description: "Fields to sort the response data by, following the order of the parameters from left to right.\n\n* Can contain multiple fields in the format: `fieldName:sortDirection`, separated by commas.\n\n* The colon with the sort direction parameter is optional.\n\n* Descending order is used only if the sort direction equals `desc` or `DESC`.\n\n* Ascending order is assumed in all other cases.\n\nWhile sorting by a localized field, the following rules apply:\n\n* If a localized field includes a language code, that language is used.  \n  Example: `name.en:ASC` → English (`en`) is used for sorting the `name` property.  \n  The language suffix takes precedence over the `Accept-Language` header.\n\n* If a localized field does not include a language code, the `Accept-Language` header is used.  \n  Example: `name:ASC` with `Accept-Language: de` → German (`de`) is used for sorting.\n\n* If a localized field has no language code and the `Accept-Language` header contains `*`,  \n  the default language from the configuration service is used.  \n  Example: `name:ASC`, `Accept-Language: *`, default language = `pl` → Polish (`pl`) is used.\n\n* If a localized field has no language code and there is no `Accept-Language` header,  \n  the default language from the configuration service is used.\n"
      schema:
        type: string
        example: name,code:desc
    trait_tenant:
      name: tenant
      in: path
      required: true
      description: 'The tenant that the caller is acting upon.


        Please note that this value is always lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
    trait_region_name_query_param:
      name: name
      in: query
      required: false
      schema:
        type: string
      description: "Region names. When specified, only regions containing the specified names are returned.\n\n**Important**: See how the `Accept-Language` header influences this parameter:\n  * If The `Accept-Language` header is set to `*`, you need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `*` and you want to find English names containing the word \"America\", this parameter should be set to \"name.en=America\"\n\n  * If the `Accept-Language` header is set to a particular language or not specified, you do not need to specify a language in this parameter.\n\n    For example, if the `Accept-Language` header is set to `en` and you want to find names containing the word \"America\", this parameter should be set to \"name=America\"\n\n**Note**: When filtering the results with this field, the `contains` operator is used. The operator is case-insensitive.\n"
  examples:
    InternalServiceError500_Example:
      value:
        code: 500
        status: Internal Server Error
        message: A server-side exception occurred that prevented the system from correctly returning the result.
    NotFound404_CountryNotFound:
      value:
        entityId: DE
        code: 404
        status: Not Found
        message: The country with the requested code does not exist.
    BadRequest400_AmbiguousTenant:
      value:
        status: Bad Request
        code: 400
        message: Tenant in the header is not matching with the one provided in the URI.
  responses:
    BadRequest_400:
      description: Request was syntactically incorrect. Details are provided in the response payload.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Ambiguous tenant:
              $ref: '#/components/examples/BadRequest400_AmbiguousTenant'
    NotFound_404:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Country not found:
              $ref: '#/components/examples/NotFound404_CountryNotFound'
    InternalServiceError_500:
      description: Internal Service Error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorMessage'
          examples:
            Internal service error:
              $ref: '#/components/examples/InternalServiceError500_Example'
    GetRegions:
      description: The request was successful. A list of regions is returned.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/region'
          examples:
            List of regions:
              value:
              - code: Europe
                name:
                  en: Europe
                  pl: Europa
                metadata:
                  createdAt: '2022-03-31T13:18:02.379Z'
                  modifiedAt: '2022-03-31T13:18:02.379Z'
                  version: 1
    GetRegion:
      description: The request was successful. The requested region is returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/region'
          examples:
            Requested regions:
              value:
                code: Europe
                name:
                  en: Europe
                  pl: Europa
                metadata:
                  createdAt: '2022-03-31T13:18:02.379Z'
                  modifiedAt: '2022-03-31T13:18:02.379Z'
                  version: 1
  schemas:
    metadata:
      type: object
      properties:
        createdAt:
          description: Date and time when the document was created.
          type: string
        modifiedAt:
          description: Date and time when the document was last modified.
          type: string
        version:
          minimum: 1
          type: integer
          description: Version of the document.
      required:
      - createdAt
      - modifiedAt
      - version
    errorMessage:
      title: Error
      description: Schema for API specified errors.
      type: object
      properties:
        status:
          description: Original HTTP error reason.
          type: string
        code:
          description: Original HTTP error code, should be consistent with the response HTTP code.
          type: integer
        message:
          description: Descriptive error message for debugging.
          type: string
        details:
          description: List of problems causing this error.
          type: array
          items:
            title: Error Detail
            description: Schema for specific error cause.
            type: string
      required:
      - status
      - code
    region:
      title: Region
      type: object
      properties:
        code:
          type: string
          description: The region code.
        name:
          description: The localized name of the region. The value is returned as a map where the key is a language code and the value is a translation for the given language.
          type: object
          additionalProperties:
            type: string
        metadata:
          $ref: '#/components/schemas/metadata'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            country.country_read: Needed to read countries
            country.country_manage: Needed to manage countries
            country.region_read: Needed to read regions
x-refined-from:
- emporix-country-service-openapi.yml
- emporix-country-service-openapi.yml