openapi: 3.0.2
info:
  title: 'GA4GH service-info API specification'
  description: 'A way for a service to describe basic metadata concerning a service alongside a set of capabilities and/or limitations of the service. More information on [GitHub](https://github.com/ga4gh-discovery/ga4gh-service-info/).'
  version: 1.0.0
  license:
    name: 'Apache 2.0'
    url: 'https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/develop/LICENSE'
  contact:
    name: 'GA4GH Discovery Networks Team'
    email: 'ga4gh-discovery-networks@ga4gh.org'
security:
  - bearerAuth: []
paths:
  /service-info:
    get:
      summary: 'Show information about this service. It is assumed that removing this endpoint from a URL will result in a valid URL to query against'
      operationId: getServiceInfo
      tags:
        - service-info
      responses:
        '200':
          description: 'A successful operation to request the service information about this running service.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Service:
      description: 'GA4GH service'
      type: object
      required:
        - id
        - name
        - type
        - organization
        - version
      properties:
        id:
          type: string
          description: 'Unique ID of this service. Reverse domain name notation is recommended, though not required. The identifier should attempt to be globally unique so it can be used in downstream aggregator services e.g. Service Registry.'
          example: 'org.ga4gh.myservice'
        name:
          type: string
          description: 'Name of this service. Should be human readable.'
          example: 'My project'
        type:
          $ref: '#/components/schemas/ServiceType'
        description:
          type: string
          description: 'Description of the service. Should be human readable and provide information about the service.'
          example: 'This service provides...'
        organization:
          type: object
          description: 'Organization providing the service'
          required:
            - name
            - url
          properties:
            name:
              type: string
              description: 'Name of the organization responsible for the service'
              example: 'My organization'
            url:
              type: string
              format: uri
              description: 'URL of the website of the organization (RFC 3986 format)'
              example: 'https://example.com'
        contactUrl:
          type: string
          format: uri
          description: 'URL of the contact for the provider of this service, e.g. a link to a contact form (RFC 3986 format), or an email (RFC 2368 format).'
          example: 'mailto:support@example.com'
        documentationUrl:
          type: string
          format: uri
          description: 'URL of the documentation of this service (RFC 3986 format). This should help someone learn how to use your service, including any specifics required to access data, e.g. authentication.'
          example: 'https://docs.myservice.example.com'
        createdAt:
          type: string
          format: date-time
          description: 'Timestamp describing when the service was first deployed and available (RFC 3339 format)'
          example: '2019-06-04T12:58:19Z'
        updatedAt:
          type: string
          format: date-time
          description: 'Timestamp describing when the service was last updated (RFC 3339 format)'
          example: '2019-06-04T12:58:19Z'
        environment:
          type: string
          description: 'Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Suggested values are prod, test, dev, staging. However this is advised and not enforced.'
          example: 'test'
        version:
          type: string
          description: 'Version of the service being described. Semantic versioning is recommended, but other identifiers, such as dates or commit hashes, are also allowed. The version should be changed whenever the service is updated.'
          example: '1.0.0'
    ServiceType:
      description: 'Type of a GA4GH service'
      type: object
      required:
        - group
        - artifact
        - version
      properties:
        group:
          type: string
          description: 'Namespace in reverse domain name format. Use `org.ga4gh` for implementations compliant with official GA4GH specifications. For services with custom APIs not standardized by GA4GH, or implementations diverging from official GA4GH specifications, use a different namespace (e.g. your organization''s reverse domain name).'
          example: 'org.ga4gh'
        artifact:
          type: string
          description: 'Name of the API or GA4GH specification implemented. Official GA4GH types should be assigned as part of standards approval process. Custom artifacts are supported.'
          example: 'beacon'
        version:
          type: string
          description: 'Version of the API or specification. GA4GH specifications use semantic versioning.'
          example: '1.0.0'