X-Road (NIIS) Service Descriptions API

openapi: 3.2.0
info:
  title: X Road Global Service Descriptions API
  version: 2.1.0
  contact:
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
    email: info@niis.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged service-descriptions across 2 of this provider''s published API definitions: security-server-admin-openapi.yaml, x-road-global-security-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
  description: basepath for API v1
security:
- ApiKeyAuth: []
tags:
- name: service-descriptions
  description: service descriptions endpoints
paths:
  /service-descriptions/{id}:
    get:
      tags:
      - service-descriptions
      summary: get service description with provided id
      operationId: getServiceDescription
      description: Administrator views a service description with a certain id.
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      responses:
        '200':
          description: wanted service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    patch:
      tags:
      - service-descriptions
      summary: update url or service code for the selected service description
      operationId: updateServiceDescription
      description: 'Administrator updates the selected service description.


        This endpoint can also return metadata in the error response if updating the service description fails due to invalid URLs, already existing service description or already existing services. If updating the service description fails due to an invalid service URL, the error response will have the error code invalid_service_url and the metadata will contain a list of invalid URLs. If updating the service description fails due to an already existing service description, the error response will have the error code url_already_exists and the metadata will contain the existing URL. If updating the service description fails due to already existing services, the metadata array will have a more complex format. See the description of the ''409'' response in this endpoint.


        This endpoint can return a warnings response which can be ignored by setting ServiceDescriptionUpdate.ignore_warnings = true. If ServiceDescriptionUpdate.ignore_warnings = false, a warnings response will be returned if any one of the following conditions is true


        WSDL or OpenAPI3 validation fails and validation warnings are returned (warning code will be either wsdl_validation_warnings or openapi_validation_warnings)


        existing services will be removed (warning code deleting_services and the warning metadata contains a list of service codes that will be removed)


        new services will be added (warning code adding_services and the warning metadata contains a list of service codes that will be added)'
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceDescriptionUpdate'
      responses:
        '200':
          description: service description modified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: there are warnings or errors related to the service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/UpdateServiceDescriptionWarningExample'
                validation_errors_response:
                  $ref: '#/components/examples/ValidationErrorsExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: <h3>An existing item already exists</h3> <p> If there are existing WSDL services with the same name, the error response will include the existing services' names and the containing WSDL's URL in the metadata array. </p> <p> In this case the error code <code>service_already_exists</code> (WSDL) or <code>service_code_already_exists</code> (OPENAPI3) is used and the entries in the metadata array are ordered in following way <ul> <li>metadata has a list of strings [C1,U1,C2,U2....Cn,Un] where</li> <li>C1 = duplicate service full code</li> <li>U1 = URL of the existing WSDL that has the duplicate</li> </ul> </p> <strong>See the example</strong>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ServiceDescriptionErrorWithMetadataExample'
        '500':
          description: internal server error
    delete:
      tags:
      - service-descriptions
      summary: delete service description
      operationId: deleteServiceDescription
      description: Administrator deletes the service description.
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      responses:
        '204':
          description: service description deletion was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /service-descriptions/{id}/disable:
    put:
      tags:
      - service-descriptions
      summary: disable selected service description
      operationId: disableServiceDescription
      description: Administrator disables service description.
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceDescriptionDisabledNotice'
      responses:
        '204':
          description: service description disabled
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /service-descriptions/{id}/enable:
    put:
      tags:
      - service-descriptions
      summary: enable selected service description
      operationId: enableServiceDescription
      description: Administrator enables service description.
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      responses:
        '204':
          description: service description enabled
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /service-descriptions/{id}/refresh:
    put:
      tags:
      - service-descriptions
      summary: refresh selected service description
      operationId: refreshServiceDescription
      description: 'Administrator refreshes service description.


        This endpoint can also return metadata in the error response if refreshing the service description fails due to invalid URLs, already existing service description or already existing services. If refreshing the service description fails due to an invalid service URL, the error response will have the error code invalid_service_url and the metadata will contain a list of invalid URLs. If refreshing the service description fails due to an already existing service description, the error response will have the error code url_already_exists and the metadata will contain the existing URL. If refreshing the service description fails due to already existing services, the metadata array will have a more complex format. See the description of the ''409'' response in this endpoint.


        This endpoint can return a warnings response which can be ignored by setting IgnoreWarnings.ignore_warnings = true. If IgnoreWarnings.ignore_warnings = false, a warnings response will be returned if any one of the following conditions is true


        WSDL or OpenAPI3 validation fails and validation warnings are returned (warning code will be either wsdl_validation_warnings or openapi_validation_warnings)


        existing services will be removed (warning code deleting_services and the warning metadata contains a list of service codes that will be removed)


        new services will be added (warning code adding_services and the warning metadata contains a list of service codes that will be added)'
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IgnoreWarnings'
      responses:
        '200':
          description: service description refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDescription'
        '400':
          description: there are warnings or errors related to the service description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
                warnings_response:
                  $ref: '#/components/examples/RefreshServiceDescriptionWarningExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: <h3>An existing item already exists</h3> <p> If there are existing WSDL services with the same name, the error response will include the existing services' names and the containing WSDL's URL in the metadata array. </p> <p> In this case the error code <code>service_already_exists</code> (WSDL) or <code>service_code_already_exists</code> (OPENAPI3) is used and the entries in the metadata array are ordered in following way <ul> <li>metadata has a list of strings [C1,U1,C2,U2....Cn,Un] where</li> <li>C1 = duplicate service full code</li> <li>U1 = URL of the existing WSDL that has the duplicate</li> </ul> </p> <strong>See the example</strong>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ServiceDescriptionErrorWithMetadataExample'
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /service-descriptions/{id}/services:
    get:
      tags:
      - service-descriptions
      summary: get services for the selected service description
      operationId: getServiceDescriptionServices
      description: Administrator views the services for the selected service description.
      parameters:
      - in: path
        name: id
        description: id of the service description
        required: true
        schema:
          type: string
          format: text
          minLength: 1
      responses:
        '200':
          description: list of services
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                description: array of service objects
                items:
                  $ref: '#/components/schemas/Service'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
components:
  schemas:
    ServiceDescription:
      type: object
      description: WSDL/OPENAPI3/REST service
      required:
      - id
      - url
      - type
      - disabled
      - disabled_notice
      - refreshed_at
      - services
      - client_id
      properties:
        id:
          type: string
          description: unique identifier
          example: 123
        url:
          type: string
          format: url
          description: service url
          example: http://dev.xroad.rocks/services.wsdl
          minLength: 1
          maxLength: 255
        type:
          $ref: '#/components/schemas/ServiceType'
        disabled:
          type: boolean
          description: service disabled
          example: true
        disabled_notice:
          type: string
          format: text
          description: disabled notice
          example: default_disabled_service_notice
          minLength: 0
          maxLength: 255
        refreshed_at:
          type: string
          format: date-time
          description: time for service refresh
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        services:
          type: array
          description: service description services
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Service'
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          minLength: 1
          maxLength: 255
    ServiceDescriptionUpdate:
      type: object
      description: request object for updating a service description url or service code
      required:
      - type
      - url
      properties:
        url:
          type: string
          format: text
          description: path for the service description file
          example: https://domain.com/service
          minLength: 1
          maxLength: 255
        rest_service_code:
          type: string
          format: text
          description: service code for REST service
          example: exampleServiceCode
          minLength: 1
          maxLength: 255
        new_rest_service_code:
          type: string
          format: test
          description: new service code for REST service
          example: newExampleServiceCode
          minLength: 1
          maxLength: 255
        ignore_warnings:
          type: boolean
          description: if true, any ignorable warnings are ignored. if false (or missing), any warnings cause request to fail
          default: false
        type:
          $ref: '#/components/schemas/ServiceType'
    IgnoreWarnings:
      type: object
      properties:
        ignore_warnings:
          type: boolean
          default: false
          description: if true, any ignorable warnings are ignored. if false (or missing), any warnings cause request to fail
    Endpoint:
      type: object
      description: Endpoint for a service
      required:
      - service_code
      - method
      - path
      properties:
        id:
          type: string
          description: unique identifier
          example: 15
        service_code:
          type: string
          example: example_service_code
          description: service code
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          readOnly: true
          minLength: 1
          maxLength: 255
        method:
          type: string
          description: http method mapped to this endpoint
          example: GET
          enum:
          - '*'
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
          - HEAD
          - OPTIONS
          - TRACE
        path:
          type: string
          description: relative path where this endpoint is mapped to
          example: /foo
        generated:
          type: boolean
          description: has endpoint been generated from openapi3 description
          example: true
          readOnly: true
    Service:
      type: object
      description: service for the service description
      required:
      - id
      - service_code
      - url
      - timeout
      - service_description_id
      - client_id
      properties:
        id:
          type: string
          format: text
          description: encoded service id, including client id
          example: CS:ORG:Client:myService.v1
          minLength: 1
          maxLength: 1279
        service_description_id:
          type: string
          description: unique identifier
          example: 123
        client_id:
          type: string
          format: text
          description: <instance_id>:<member_class>:<member_code>:<subsystem>(optional)
          example: FI:GOV:123:ABC
          minLength: 1
          maxLength: 255
        full_service_code:
          type: string
          format: text
          description: encoded service code and version
          example: myService.v1
          minLength: 1
          maxLength: 511
        service_code:
          type: string
          format: text
          description: encoded service code
          example: myService
          minLength: 1
          maxLength: 255
        timeout:
          type: integer
          format: int32
          description: service time out value
          example: 60
          minimum: 0
          maximum: 1000
        title:
          type: string
          readOnly: true
          format: text
          description: service title
          example: client deletion
          minLength: 1
          maxLength: 255
        ssl_auth:
          type: boolean
          description: service ssl auth
          example: true
        subjects_count:
          type: integer
          format: int32
          description: count of acl subjects
          example: 5
          minimum: 0
          maximum: 100000
        url:
          type: string
          format: url
          description: service url
          example: https://domain.com/service
          minLength: 1
          maxLength: 255
        endpoints:
          type: array
          description: list of endpoints linked to this service
          items:
            $ref: '#/components/schemas/Endpoint'
    ErrorInfo:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
    ServiceType:
      type: string
      format: text
      description: service type
      example: WSDL
      enum:
      - WSDL
      - REST
      - OPENAPI3
    ServiceDescriptionDisabledNotice:
      type: object
      properties:
        disabled_notice:
          type: string
          format: text
          description: disabled service notice
          minLength: 0
          maxLength: 255
  examples:
    RefreshServiceDescriptionWarningExample:
      summary: Warning response when refreshing a service description adds or removes services
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
        - code: adding_services
          metadata:
          - newService.v1
          - anotherNewService.v1
        - code: deleting_services
          metadata:
          - someOldService.v1
    ErrorExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    UpdateServiceDescriptionWarningExample:
      summary: Warning response when updating a service description adds or removes services
      value:
        status: 400
        error:
          code: warnings_detected
        warnings:
        - code: adding_services
          metadata:
          - newService.v1
          - anotherNewService.v1
        - code: deleting_services
          metadata:
          - someOldService.v1
    ServiceDescriptionErrorWithMetadataExample:
      summary: Error when adding a service description and some duplicate services already exist
      value:
        status: 409
        error:
          code: service_already_exists
          metadata:
          - duplicateService.v1
          - http://xroad-lxd-cs.lxd/duplicate1.wsdl
          - anotherDuplicateService.v1
          - http://xroad-lxd-cs.lxd/duplicate1.wsdl
          - yetAnotherDuplicateService.v1
          - http://xroad-lxd-cs.lxd/someOtherWsdl.wsdl
    ValidationErrorsExample:
      summary: Validation errors response body example
      value:
        status: 400
        error:
          code: validation_failure
          validation_errors:
            clientAdd.client.memberCode:
            - NoPercent
            clientAdd.client.subsystemCode:
            - NoPercent
            - NoBackslashes
    ErrorWithMetadataExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: X-Road-ApiKey token=<api key>
x-refined-from:
- security-server-admin-openapi.yaml
- x-road-global-security-server-admin-openapi.yml