swagger: '2.0'
info:
  title: Maps4News API
  version: '0.1'
host: api.maps4news.com
# HTTPS is enforced
schemes:
  - https

basePath: /v1

produces:
  - application/json

paths:
  /login:
    post:
      description: |
        This endpoint allows the user to authenticate and obtain an api key.
      parameters:
        - name: email
          in: query
          description: The user's email
          required: true
          type: string
          format: email
        - name: password
          in: query
          description: The user's password
          required: true
          type: string
          format: password
      tags:
        - User
        - Authentication
      responses:
        200:
          description: Api Token
          schema:
            $ref: '#/definitions/Token'
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        401:
          description: Invalid or missing api token
          schema:
            $ref: '#/definitions/Error'

  /users:
    get:
      description: |
        Get all users you have acess to.

        - Organisation admins will get all users in their organisation.

        - Normal users will only get their own user object.
      tags:
        - User
      security:
        - api_key: [ ]
      responses:
        200:
          description: Array of user objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        401:
          description: Invalid or missing api token.
          schema:
            $ref: '#/definitions/Error'

  /users/{id}:
    get:
      description: Used to get a user that you have access to.
      tags:
        - User
      security:
        - api_key: []
      parameters:
        - $ref: '#/parameters/id'
      responses:
        200:
          description: User object.
          schema:
            $ref: '#/definitions/User'
        401:
          description: Invalid or missing api token.
          schema:
            $ref: '#/definitions/Error'

  /users/me:
    get:
      description: |
        Alias of `/users/{id}`. (All subroutes are compatible. e.g. `/users/me/svgs`)

        Get the current users's object
      tags:
        - User
      security:
        - api_key: []
      responses:
        200:
          description: Array of svg objects.
          schema:
            $ref: '#/definitions/User'
        401:
          description: Invalid or missing api token.
          schema:
            $ref: '#/definitions/Error'

  /users/{id}/dimensions:
    get:
      description: Get all the dimensions the user has access to.
      tags:
        - User
        - Dimension
      security:
        - api_key: []
      parameters:
        - $ref: '#/parameters/id'
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/per_page'
        - $ref: '#/parameters/X-Page'
        - $ref: '#/parameters/X-Per-Page'
      responses:
        200:
          description: Array of dimension objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/Dimension'
        401:
          description: Invalid or missing api token.
          schema:
            $ref: '#/definitions/Error'


  # /users/{id}/features:

  # /users/{id}/fonts:

  # /users/{id}/jobs:

  # For=visibility
  # /users/{id}/shares:

  /users/{id}/svgs:
    get:
      description: Get all the svgs the user has access to.
      tags:
        - User
        - Svg
      security:
        - api_key: []
      parameters:
        - $ref: '#/parameters/id'
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/per_page'
        - $ref: '#/parameters/X-Page'
        - $ref: '#/parameters/X-Per-Page'
      responses:
        200:
          description: Array of svg objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/Svg'
        401:
          description: Invalid or missing api token.
          schema:
            $ref: '#/definitions/Error'

  # /users/{id}/vector_layers:

parameters:
  id:
    name: id
    in: path
    description: The ID of the resource.
    required: true
    type: integer
  page:
    name: page
    in: query
    description: |
      The page you want to visit.

      - Default: 1
    required: false
    type: integer
  per_page:
    name: per_page
    in: query
    description: |
      The number of resources on one page

      - Default: 12

      - Minimum: 1

      - Maximum: 50
    type: integer
    required: false

  X-Per-Page:
    name: X-Per-Page
    in: header
    description: Same as `per_page`
    type: integer
    required: false

  X-Page:
    name: X-Page
    in: header
    type: integer
    description: Same as `page`
    required: false

securityDefinitions:
  api_key:
    type: apiKey
    name: X-Api-Token
    description: The api token
    in: header

definitions:
  timestamp:
    type: string
    format: DateTime
    description: ISO 8601/RFC3339 formatted DateTime
    example: 2016-03-17T16:35:01Z

  Token:
    type: object
    properties:
      token:
        type: string
        description: Unique user token used for identification
        example: Pjde6XYkfOhRErZaFn0ibNVbXGP4CE8UcUpMDBg4

  Error:
    type: object
    properties:
      error:
        type: string
        description: Error message
        example: An error occoured

  #############
  #           #
  #   Models  #
  #           #
  #############

  Contract:
    type: object
    properties:
      name:
        type: string
        example: string
      organisation:
        $ref: '#/definitions/Organisation'
      credits:
        type: integer
        description: >-
          The amount of credits that this contract adds to the
          organisation. If the value is 0 then the contract is
          a flatrate contract.
        example: 100
      credit_period:
        type: integer
        description: >-
          The number of credits that can be
          used within a certain period.
      period_length:
        type: integer
        description: The lenght of a period, in days.
      date_start:
        $ref: '#/definitions/timestamp'
      date_end:
        $ref: '#/definitions/timestamp'
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Dimension:
    type: object
    properties:
      id:
        type: integer
        example: 47
      dimension_set_id:
        type: integer
        example: 1
      name:
        type: string
        example: A5 landscape
      width:
        type: number
        format: float
      height:
        type: number
        format: float
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  DimensionSet:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        example: Standard
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'
      dimensions:
        type: array
        items:
          $ref: '#/definitions/Dimension'

  Faq:
    type: object
    properties:
      id:
        type: integer
        description: Identifier
        example: 1
      title:
        type: string
        description: Question
        example: Frequently asked question
      description:
        type: string
        description: Answer
        example: Unescaped HTML formatted answer
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Feature:
    type: object
    properties:
      id:
        type: integer
        example: 4
      name:
        type: string
        example: Web
      description:
        type: string
        example: Allows web output
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Font:
    type: object
    properties:
      name:
        type: string
        example: Helvetica-Condensed-Bold
      style:
        type: string
        enum:
          - normal
          - italic
          - oblique
          - bold
          - thin
        example: normal
      weight:
        type: integer
        minimum: 0
        example: 700
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  FontFamily:
    type: object
    properties:
      name:
        type: string
        example: Helvetica Condensed
      fonts:
        type: array
        items:
          $ref: '#/definitions/Font'
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'
      fonts:
        type: array
        items:
          $ref: '#/definitions/Font'

  IP:
    type: object
    properties:
      user_id:
        type: integer
        example: 1
      ip_address:
        type: string
        description: IPv4 or IPv6 address
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Job:
    type: object
    properties:
      id:
        type: integer
        example: 1
      user_id:
        type: integer
        example: 1
      mapstyle_set:
        $ref: '#/definitions/MapstyleSet'
      title:
        type: string
        description: Title for the job
      description:
        type: string
        description: Description of the job
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  JobResult:
    type: object
    properties:
      id:
        type: integer
        example: 1
      # job_id:
      #   type: integer
      #   example: 1
      job:
        $ref: '#/definitions/Job'
      # job_revision_id:
      #   type: integer
      #   example: 1
      job_revision:
        $ref: '#/definitions/JobRevision'
      # mapstyle_id:
      #   type: integer
      #   example: 1
      mapstyle:
        $ref: '#/definitions/Mapstyle'
      status:
        type: integer
        example: 1
        # TODO description
      software_version:
        type: integer
        format: double
        example: 1.0
        description: The version of the backend that was used
      interface_version:
        type: string
        example: '2.6.0b'
        description: The version of the frontend that was used
      fix:
        type: boolean
        example: true
        # TODO description
      process_start:
        $ref: '#/definitions/timestamp'
      process_end:
        $ref: '#/definitions/timestamp'
      dealt_with:
        type: boolean
        example: true
        description: If the issue has been resolved
      log: # TODO remove
        type: string
        description: The  log from the render job
      preview_path: # TODO remove
        type: string
      file_path: # TODO remove
        type: string
      bought:
        type: boolean
        example: true
        description: If the user paid for the map with a credit
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  JobRevision:
    type: object
    properties:
      job_id:
        type: integer
        example: 1
      revision:
        type: integer
        example: 1
      object:
        type: string
        format: json
      screenshot_url:
        type: string
        example: http://url.to/image.png
      archived:
        type: boolean
        description: If the revision was used in a render job
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  JobShare:
    type: object
    properties:
      id:
        type: integer
        example: 1
      # job_id:
      #   type: integer
      #   example: 1
      job:
        $ref: '#/definitions/Job'
      visibility:
        type: string
        enum:
            - private
            - organisation
            - public
        description: Who can view the jobshare.
      hashkey:
        type: integer
        example: 1769919554
        # TODO description
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Language:
    type: object
    properties:
      name:
        type: string
        example: English
      code:
        type: string
        description: 3 character language code
        example: eng
      locale:
        type: string
        example: en_GB
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Mapstyle:
    type: object
    properties:
      id:
        type: integer
        example: 1
      mapstyle_set_id:
        type: integer
        example: 1
      name:
        type: string
        example: NEWS10k.xml
      preview_image:
        type: string
        description: url to the mapstyle preview image
      scale_min:
        minimum: 0
        example: 0
        description: The lowest scale that the Mapstyle can be used at. Must be smaller than scale_min
      scale_max:
        minimum: 1
        example: 16249
        description: The highest scale that the Mapstyle can be used at. Must be greater than scale_min
      description:
        type: string
        example: 1:10.000
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  MapstyleSet:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        example: Clear News
      description:
        type: string
        example: A clean and simplified bright map style.
      version:
        type: number
        format: double
        example: 2.0
      supports_svg:
        type: boolean
        description: Indicates if the MapstyleSet supports SVG output
        example: false
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'
      mapstyles:
        type: array
        items:
          $ref: '#/definitions/Mapstyle'

  Notification:
    type: object
    properties:
      id:
        type: integer
        example: 1
      title:
        type: string
        example: Maps4News Maintenance message
      description:
        type: string
        example: 'Maps4News Maintenance Message: Maintenance is scheduled for Tuesday, 13 October 2015, between 05:00 AM and 05:30 AM GMT. {...}'
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  Organisation:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        example: ACME Inc Editors
      company:
        type: string
        example: ACME Inc
      city:
        type: string
        example: New York City
      country:
        type: string
        example: United States
      address:
        type: string
        example: 14 North Moore Street
      credits:
        type: integer
        description: Availible credits
        example: 27
      sales_representative:
        $ref: '#/definitions/User'
      manager:
        $ref: '#/definitions/User'
      fonts:
        type: array
        items:
          $ref: '#/definitions/Font'
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'
      users:
        type: array
        items:
          $ref: '#/definitions/User'

  SingleSignOn:
    type: object
    properties:
      id:
        type: integer
        example: 1
      # user_id:
      #   type: integer
      #   example: 1
      user:
        $ref: '#/definitions/User'
      sso_id:
        type: integer
        example: 1
        # TODO description
      type:
        type: string
        example: 'accounts.google.com'
        description: The sso service
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  StudioLog:
    type: object
    # TODO refector

  Svg:
    type: object
    properties:
      id:
        type: integer
        example: 1
      # svg_set_id:
      #   type: integer
      #   example: 1
      svg_set:
        $ref: '#/definitions/SvgSet'
      name:
        type: string
        example: White Box
        description: The name of the svg
      svg_string:
        type: string
        format: svg
      resize_factor:
        type: integer
        format: float
        example: 0.1
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  SvgSet:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        example: Textboxes
        description: The name of the svg set
      # svg_set_type_id:
      #   type: integer
      #   example: 1
      #   description: The id of the svg set type
      svg_set_type:
        $ref: '#/definitions/SvgSetType'
      supports_interactive:
        type: boolean
        example: true
        description: If the svg set is supported by interactive
      import:
        type: boolean
        example: true
        # TODO description
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  SvgSetType:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        example: Icons

  User:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
        description: Full Name
        example: John Doe
      email:
        type: string
        example: john.doe@example.com
      phone:
        type: string
        example: +1 555 2368
        description: 'Who you gonna call? https://nnmm.nl/?F7p'
      profession:
        type: string
        example: 'Editor'
      organisation_id:
        type: integer
        example: 1
      language:
        $ref: '#/definitions/Language'
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'

  VectorLayer:
    type: object
    properties:
      id:
        type: integer
        example: 1
      name:
        type: string
      path:
        type: string
      bounding_box:
        type: string
      version:
        type: integer
        format: double
      image:
        type: string
      scale_min:
        minimum: 0
        example: 0
        description: The lowest scale that the vector layer can be used at. Must be smaller than scale_max.
      scale_max:
        minimum: 1
        example: 16249
        description: The highest scale that the vector layer can be used at. Must be greater than scale_min.
      created_at:
        $ref: '#/definitions/timestamp'
      updated_at:
        $ref: '#/definitions/timestamp'