swagger.yaml

swagger: "2.0"
info:
  title: Go Auth service
  description: HTTP API for authentication and authorization.
  version: "1.0.0"
consumes:
  - "application/json"
produces:
  - "application/json"
paths:
  /users:
    post:
      summary: Registers user account
      description: |
        Registers new user account given email and password. New account will
        be uniquely identified by its email address.
      tags:
        - users
      parameters:
        - name: user
          description: JSON-formatted document describing the new user.
          in: body
          schema:
            $ref: "#/definitions/User"
          required: true
      responses:
        201:
          description: Registered new user.
        400:
          description: Failed due to malformed JSON.
        409:
          description: Failed due to using an existing email address.
        500:
          $ref: "#/responses/ServiceError"
    get:
      summary: Retrieves user accounts
      description: |
        Retrieves a list of user accounts. Due to performance concerns, data
        is retrieved in subsets. The API clients must ensure that the entire
        dataset is consumed either by making subsequent requests, or by
        increasing the subset size of the initial request.
      tags:
        - channels
      parameters:
        - $ref: "#/parameters/Authorization"
        - $ref: "#/parameters/Size"
        - $ref: "#/parameters/Offset"
      responses:
        200:
          description: Data retrieved.
          headers:
            X-Count:
              type: integer
              description: |
                Total number of managed channels. This value can be used to
                implement the paging strategy on API clients.
          schema:
            $ref: "#/definitions/UserList"
        400:
          description: Failed due to malformed query parameters.
        403:
          description: Missing or invalid access token provided.
        500:
          $ref: "#/responses/ServiceError"
  /users/{id}:
    get:
      summary: Retrieves user info
      tags:
        - channels
      parameters:
        - $ref: "#/parameters/Authorization"
        - $ref: "#/parameters/Id"
      responses:
        200:
          description: Data retrieved.
          schema:
            $ref: "#/definitions/UserRes"
        403:
          description: Missing or invalid access token provided.
        404:
          description: Channel does not exist.
        500:
          $ref: "#/responses/ServiceError"
    put:
      summary: Updates user info
      description: |
        Update is performed by replacing the current resource data with values
        provided in a request payload. Resource's unique identifier will not be
        affected.
      tags:
        - channels
      parameters:
        - $ref: "#/parameters/Authorization"
        - $ref: "#/parameters/Id"
        - name: channel
          description: JSON-formatted document describing the updated channel.
          in: body
          schema:
            $ref: "#/definitions/UserReq"
          required: true
      responses:
        200:
          description: User updated.
        400:
          description: Failed due to malformed JSON.
        403:
          description: Missing or invalid access token provided.
        404:
          description: User does not exist.
        500:
          $ref: "#/responses/ServiceError"
    delete:
      summary: Removes a user account
      description: |
        Removes user account. The service will ensure that the subscribed apps and
        devices are unsubscribed from the removed channel.
      tags:
        - channels
      parameters:
        - $ref: "#/parameters/Authorization"
        - $ref: "#/parameters/Id"
      responses:
        204:
          description: User removed.
        403:
          description: Missing or invalid access token provided.
        500:
          $ref: "#/responses/ServiceError"
  /login:
    post:
      summary: User authentication
      description: |
        Generates an access token when provided with proper credentials.
      tags:
        - users
      parameters:
        - name: credentials
          description: JSON-formatted document containing user credentials.
          in: body
          schema:
            $ref: "#/definitions/User"
          required: true
      responses:
        201:
          description: User authenticated.
          schema:
            $ref: "#/definitions/Token"
        400:
          description: |
            Failed due to malformed JSON or using an invalid credentials.
        500:
          $ref: "#/responses/ServiceError"
  /auth:
    get:
      summary: Checks the token validity
      description: |
        If the request is made using valid token, an identifier bound
        to that token will be returned.
      tags:
        - access control
      parameters:
        - $ref: "#/parameters/Authorization"
      responses:
        200:
          description: ID retrieved
          headers:
            X-client-id:
              type: string
              description: ID of the entity bound to the provided access key.
        403:
          description: Missing or invalid access token provided.

parameters:
  Authorization:
    name: Authorization
    description: User's access token.
    in: header
    type: string
    required: true
  Id:
    name: id
    description: Unique resource identifier.
    in: path
    type: string
    format: uuid
    required: true
  Size:
    name: size
    description: Size of the subset to retrieve.
    in: query
    type: integer
    default: 10
    required: false
  Offset:
    name: offset
    description: Number of items to skip during retrieval.
    in: query
    type: integer
    default: 0
    required: false

responses:
  ServiceError:
    description: Unexpected server-side error occured.

definitions:
  UserList:
    type: object
    properties:
      channels:
        type: array
        minItems: 0
        uniqueItems: true
        items:
          $ref: "#/definitions/UserRes"
    required:
      - channels
  UserRes:
    type: object
    properties:
      id:
        type: string
        description: Unique user identifier generated by the service.
      email:
        type: string
        description: Free-form channel name.
      connected:
        type: array
        minItems: 0
        uniqueItems: true
        items:
          type: string
    required:
      - id
      - name
      - connected
  ChannelReq:
    type: object
    properties:
      name:
        type: string
        description: Free-form channel name.
      connected:
        type: array
        minItems: 0
        uniqueItems: true
        items:
          type: string
  ClientList:
    type: object
    properties:
      clients:
        type: array
        minItems: 0
        uniqueItems: true
        items:
          $ref: "#/definitions/ClientRes"
    required:
      - clients
  User:
    type: object
    properties:
      email:
        type: string
        format: email
        example: "test@example.com"
        description: User's email address will be used as its unique identifier
      password:
        type: string
        format: password
        description: Free-form account password used for acquiring auth token(s).
    required:
      - email
      - password
  UserReq:
    type: object
    properties:
      type:
        type: string
        enum:
          - app
          - device
        description: Type of the client.
      name:
        type: string
        description: Free-form client name.
      meta:
        type: object
        description: Client's meta-data.
        additionalProperties:
          type: string
    required:
      - type
  Token:
    type: object
    properties:
      token:
        type: string
        description: Generated access token.
    required:
      - token