swagger.yaml

swagger: '2.0'
info:
  description: This is the API for OpenAPI space.
  version: 1.0.0
  title: OpenAPI space
  contact:
    name: APInf Oy
    url: 'http://apinf.org'
    email: info@apinf.io
host: openapi.space
basePath: /api/v1
tags:
  - name: APIs
    description: Operations for APIs
  - name: Auth
    description: Operations for authentication
schemes:
  - https
produces:
  - application/json
consumes:
  - application/json
paths:
  /auth/login:
    post:
      tags:
        - Auth
      summary: Log in to OpenAPI space
      description: ''
      x-swagger-router-controller: space.routes.auth
      operationId: login
      parameters:
        - name: body
          in: body
          description: the user credentials
          schema:
            $ref: "#/definitions/Credentials"
      responses:
        '200':
          description: login successful
          schema:
            $ref: "#/definitions/LoginToken"
        '401':
          description: invalid password
        '404':
          description: user not found
  /auth/login/apinf_token:
    post:
      tags:
        - Auth
      summary: Log in to OpenAPI space using an APInf authentication token
      description: ''
      x-swagger-router-controller: space.routes.auth
      operationId: login_apinf_token
      parameters:
        - name: body
          in: body
          description: the APInf authentication token and user ID
          schema:
            type: object
            required:
              - user_id
              - auth_token
            properties:
              user_id:
                type: string
              auth_token:
                type: string
      responses:
        '200':
          description: login successful
          schema:
            $ref: "#/definitions/LoginToken"
        '401':
          description: invalid user ID or auth token
  /auth/login/apinf:
    post:
      tags:
        - Auth
      summary: Log in to OpenAPI space using an APInf account
      description: ''
      x-swagger-router-controller: space.routes.auth
      operationId: login_apinf
      parameters:
        - name: body
          in: body
          description: the APInf username and password
          schema:
            type: object
            required:
              - username
              - password
            properties:
              username:
                type: string
              password:
                type: string
      responses:
        '200':
          description: login successful
          schema:
            $ref: "#/definitions/LoginToken"
        '401':
          description: invalid username or password
  /auth/logout:
    post:
      tags:
        - Auth
      summary: Log out from OpenAPI space
      description: ''
      x-swagger-router-controller: space.routes.auth
      operationId: logout
      responses:
        '200':
          description: logout successful
        '403':
          description: user was not logged in
      security:
        - AuthToken: []
  /auth/register:
    post:
      tags:
        - Auth
      summary: Register to OpenAPI space
      description: ''
      x-swagger-router-controller: space.routes.auth
      operationId: register
      parameters:
        - name: body
          in: body
          description: registration details
          schema:
            $ref: "#/definitions/Registration"
      responses:
        '200':
          description: registration successful
          schema:
            $ref: "#/definitions/LoginToken"
        '409':
          description: username or email taken
          schema:
            type: string
            description: defines which field is already in use
            enum:
              - EMAIL
              - USERNAME
  /auth/ping:
    post:
      tags:
        - Auth
      summary: Check whether or not you are authenticated
      description: ''
      x-swagger-router-controller: space.routes.auth
      operationId: ping
      responses:
        '200':
          description: logged in
          schema:
            $ref: "#/definitions/Registration"
        '403':
          description: not logged in
      security:
        - AuthToken: []

  /apis:
    get:
      tags:
        - APIs
      summary: Retrieves a list of currently defined APIs in API meta list format.
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: search_apis
      parameters:
        - name: query
          in: query
          description: free text query to match
          required: false
          default: ''
          type: string
        - name: limit
          in: query
          description: the maximum number of APIs to return
          required: false
          default: 10
          type: integer
        - name: offset
          in: query
          description: the offset where to start from when fetching a limited number of APIs
          required: false
          default: 0
          type: integer
        - name: sort
          in: query
          description: |
            sort criteria or result set
            * NAME -
            * UPATED
            * CREATED
            * OWNER
          required: false
          type: string
          default: NAME
          enum:
            - NAME
            - UPDATED
            - CREATED
            - OWNER
        - name: order
          in: query
          description: sort order
          required: false
          type: string
          default: ASC
          enum:
            - ASC
            - DESC
      responses:
        '200':
          description: a list of APIs in API meta list format
          schema:
            $ref: "#/definitions/APIMetaList"
      security:
        - AuthToken: []
  '/apis/{owner}':
    get:
      tags:
        - APIs
      summary: Retrieves an API meta listing of all APIs defined for this owner
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: get_owner_apis
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: sort
          in: query
          description: |
            sort criteria or result set
            * NAME -
            * UPATED
            * CREATED
            * OWNER
          required: false
          type: string
          default: NAME
          enum:
            - NAME
            - UPDATED
            - CREATED
            - OWNER
        - name: order
          in: query
          description: sort order
          required: false
          type: string
          default: ASC
          enum:
            - ASC
            - DESC
      responses:
        '200':
          description: a list of APIs in API meta list format
          schema:
            $ref: '#/definitions/APIMetaList'
      security:
        - AuthToken: []
  '/apis/{owner}/{api}':
    get:
      tags:
        - APIs
      summary: >-
        Retrieves an API meta listing for all API versions for this owner and
        API
      x-swagger-router-controller: space.routes.apis
      operationId: get_api_versions
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
      responses:
        '200':
          description: a list of API versions in API meta format
          schema:
            $ref: '#/definitions/APIMetaList'
      security:
        - AuthToken: []
    post:
      tags:
        - APIs
      summary: Saves the provided Swagger definition
      description: >-
        Saves the provided Swagger definition; the owner must match the token
        owner. The version will be extracted from the Swagger definitions
        itself.
      x-swagger-router-controller: space.routes.apis
      operationId: save_definition
      consumes:
        - application/json
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
        - name: private
          in: query
          description: Defines whether the API has to be private
          required: false
          type: boolean
          default: false
        - in: body
          name: definition
          description: the Swagger definition of this API
          required: true
          schema:
            type: object
        - name: force
          in: query
          description: force update
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: the API was successfully saved
          schema:
            $ref: "#/definitions/APIMeta"
        '201':
          description: new API was successfully saved
          schema:
            $ref: "#/definitions/APIMeta"
        '400':
          description: the Swagger definition was invalid
        '403':
          description: the API is not owned by the user
        '409':
          description: can not overwrite a published API version without force=true
        '415':
          description: invalid content type
      security:
        - AuthToken: []
    delete:
      tags:
        - APIs
      summary: Deletes the specified API
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: delete_api
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
      responses:
        '200':
          description: the API was successfully deleted
          schema:
            $ref: "#/definitions/APIMetaList"
        '403':
          description: access denied
        '404':
          description: specified API not found
      security:
        - AuthToken: []

  '/apis/{owner}/{api}/{version}':
    post:
      tags:
        - APIs
      summary: Publish a particular version of the specified API
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: publish_api_version
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
        - name: version
          in: path
          description: version identifier
          required: true
          type: string
      responses:
        '200':
          description: the API version was successfully published
        '403':
          description: access denied
        '404':
          description: specified API not found
        '409':
          description: the API version is already published
    delete:
      tags:
        - APIs
      summary: Deletes a particular version of the specified API
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: delete_api_version
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
        - name: version
          in: path
          description: version identifier
          required: true
          type: string
      responses:
        '200':
          description: the API version was successfully deleted
          schema:
            $ref: "#/definitions/APIMeta"
        '403':
          description: access denied
        '404':
          description: specified API not found
        '409':
          description: the API version is the only version of this API
      security:
        - AuthToken: []
  '/apis/{owner}/{api}/{version}/swagger.json':
    get:
      tags:
        - APIs
      summary: >-
        Retrieves the Swagger definition for the specified API and version in
        JSON format
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: get_json_definition
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
        - name: version
          in: path
          description: version identifier
          required: true
          type: string
      responses:
        '200':
          description: the Swagger API in JSON format
          schema:
            type: object
            properties: {}
        '403':
          description: "access denied: api is private"
        '404':
          description: specified API not found
      security:
        - AuthToken: []
  '/apis/{owner}/{api}/{version}/swagger.yaml':
    get:
      tags:
        - APIs
      summary: >-
        Retrieves the Swagger definition for the specified API and version in
        YAML format
      description: ''
      x-swagger-router-controller: space.routes.apis
      operationId: get_yaml_definition
      produces:
        - text/vnd.yaml
      parameters:
        - name: owner
          in: path
          description: API owner identifier
          required: true
          type: string
        - name: api
          in: path
          description: API identifier
          required: true
          type: string
        - name: version
          in: path
          description: version identifier
          required: true
          type: string
      responses:
        '200':
          description: the Swagger API in YAML format
          schema:
            type: object
            properties: {}
        '403':
          description: "access denied: api is private"
        '404':
          description: specified API not found
      security:
        - AuthToken: []
securityDefinitions:
  AuthToken:
    type: apiKey
    name: Authorization
    in: header
definitions:
  Credentials:
    type: object
    required:
      - username
      - password
    properties:
      username:
        type: string
      password:
        type: string
  Registration:
    allOf:
      - $ref: "#/definitions/Credentials"
      - type: object
        required:
          - email
        properties:
          email:
            type: string
  LoginToken:
    type: object
    properties:
      token:
        description: The authentication token sent from the server after a successful login
        type: string
      username:
        type: string
  APIMeta:
    type: object
    properties:
      owner:
        type: string
      name:
        type: string
      description:
        type: string
      versions:
        type: array
      url:
        type: string
        format: url
      created:
        type: string
        format: date-time
      modified:
        type: string
        format: date-time
      swagger:
        type: object
        description: An optional Swagger spec. Not included in meta lists.
  APIMetaList:
    type: array
    items:
      $ref: "#/definitions/APIMeta"