API Schema

The following is a definition of the API in OpenAPI 3.0.3 – note that data responses refer to JSON types defined here.

openapi: '3.0.3'
info:
  title: Safety Pool Scenario Database
  description: This API can be used to access the Safety Pool Scenario Database
  version: '1.2'
  contact:
    name: API Support
    email: support@safetypooldb.ai
servers:
  - url: 'https://live.safetypooldb.ai/api'
    description: Live server
  - url: 'https://localhost:5001/api'
    description: Local development server


components:
  responses:
      UnauthorizedError:
        description: Access token is missing or invalid
      NotFoundError:
        description: The requested resource does not exist

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  /createtoken/{apiKey}:
    post:
      description: Authenticates the caller and returns a token to be used as a bearer token for the calling the other API methods - API access must have been enabled from the UI of the NSDB first
      summary: Get a session token
      parameters:
        - name: apiKey
          description: API Key corresponding to the organisation to access
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: bearer token
                  expiration:
                    type: string
                    format: date-time
                example:
                  token: "g4ZTMyNC0wODdjLTQ3ODItYWI3ZS03YzdmNWQxYTBkZWVATUZNIiwianRpIjoiODUxY2MwMmUtOWNlZC00ZmNlLWI0MTYtYTJjOGJlZWIwNDNiIiwidW5pcXVlX25hbWUiOiJlYTg4ZTMyNC"
                  expiration: "2021-01-19T12:06:30Z"
        '400':
          description: Bad Request
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        
  /testsuites:
    get:
      description: Returns all accessible Test Suites
      summary: Get all Test Suites
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of Test Suites
          content:
            application/json:
              schema:
                externalDocs:
                  url: 'https://safetypooldb.ai/api/v1/docs#responses.testsuites'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /testsuites/{testsuiteId}:
    get:
      description: Returns the specified Test Suite
      summary: Get a Test Suite
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Content for the Test Suite
          content:
            application/json:
              schema:
                externalDocs:
                  url: 'https://safetypooldb.ai/api/v1/docs#responses.testsuite'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    parameters:
      - name: testsuiteId
        description: unique identifier of the Test Suite to get      
        in: path
        required: true
        schema:
          type: integer

  /testsuites/{testsuiteId}/routeimage:
    get:
      description: Returns a map image with showing route sections which have been selected for testing the scenarios in the Test Suite
      summary: Get a map image of testing locations for a Test Suite
      security:
        - bearerAuth: []
      responses:
        '200':
          description: image file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary            
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    parameters:
      - name: testsuiteId
        description: unique identifier of the Test Suite to get the map image for
        in: path
        required: true
        schema:
          type: integer

  /scenarios/{scenarioId}:
    get:
      description: Returns the specified Scenario
      summary: Get a Scenario
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Scenario definition
          content:
            application/json:
              schema:
                externalDocs:
                  url: 'https://safetypooldb.ai/api/v1/docs#responses.scenario'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    parameters:
      - name: scenarioId
        description: unique identifier of the Scenario to get 
        in: path
        required: true
        schema:
          type: string
          format: uuid

  /scenarios/{scenarioId}/filelist:
    get:
      description: Returns a list of files associated with the specified Scenario
      summary: Get a Scenario file list
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Scenario file list
          content:
            application/json:
              schema:
                externalDocs:
                  url: 'https://safetypooldb.ai/api/v1/docs#responses.scenariofilelist'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    parameters:
      - name: scenarioId
        description: unique identifier of the Scenario to get files for     
        in: path
        required: true
        schema:
          type: string
          format: uuid

  /scenarios/{scenarioId}/files/{fileId}:
    get:
      description: Returns the requested file for the Scenario
      summary: Get a Scenario File Attachment
      security:
        - bearerAuth: []
      responses:
        '200':
          description: file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary            
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
    parameters:
      - name: scenarioId
        description: unique identifier of the Scenario
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: fileId
        description: unique identifier of the file to get      
        in: path
        required: true
        schema:
          type: string
          format: uuid

  /ontologies/v1:
    get:
      description: Returns the Safety Pool Scenario Database Tagging Ontology in Turtle format
      summary: Get Tagging Ontology
      responses:
        '200':
          description: Turtle 
          content:
            text/plain:
              schema:
                type: string