swagger: '2.0'
info:
  version: 1.0.0
  title: Greenwire Public API
  description: 'Greenpeace Greenwire allows you connect with other volunteers, activists and groups working on environmental campaigns all across the world!'
  termsOfService: 'http://www.greenpeace.org/international/en/Help/copyright2/'
  contact:
    name: Greenpeace International contact
    url: 'http://www.greenpeace.org/international/en/about/contactus/'
  license:
    name: MIT
    url: 'http://opensource.org/licenses/MIT'
host: greenwire.greenpeace.org
basePath: /api/public
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  /volunteers:
    get:
      description: 'Gets an array of `Volunteer` object. Mandatory query param of **domain** determines the site / country the volunteers are from.'
      parameters:
        - name: domain
          type: string
          description: 'the site the users are registered on, example: netherlands'
          in: query
          required: true
        - name: limit
          in: query
          description: 'the number of desired records. Default is 5.'
          required: false
          type: string
        - name : must_have_default_avatar
          type: boolean
          in: query
          description: '1 or 0. filter on people that have the default avatar or not.'
      responses:
        '200':
          description: Successful response
          schema:
            properties:
                header:
                  $ref: '#/definitions/HeaderSuccess'
                body:
                  type: array
                  items:
                      $ref: '#/definitions/Volunteer'

  '/volunteers/{UUID}':
    get:
      description: 'Get one specific `Volunteer` object by specifying its UUID in the url path.'
      parameters:
        - name: UUID
          type: string
          in: path
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            properties:
                header:
                  $ref: '#/definitions/HeaderSuccess'
                body:
                  $ref: '#/definitions/Volunteer'
        '400':
          description: Not found
          schema:
            properties:
              header:
                  $ref: '#/definitions/HeaderError'
              body:
                type: object
                
  /groups:
    get:
      description: 'Gets an array of `Group` object. Mandatory query param of **domain** determines the site / country the group belongs to.'
      parameters:
        - name: domain
          type: string
          description: 'the site the groups belongs to, example: netherlands'
          in: query
          required: true
        - name: limit
          in: query
          description: the number of desired records
          required: false
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            properties:
                header:
                  $ref: '#/definitions/HeaderSuccess'
                body:
                  type: array
                  items:
                      $ref: '#/definitions/Group'

  '/groups/{UUID}':
    get:
      description: 'Get one `Group` object by specifying its UUID in the url path.'
      parameters:
        - name: UUID
          type: string
          in: path
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            properties:
                header:
                  $ref: '#/definitions/HeaderSuccess'
                data:
                  $ref: '#/definitions/Group'
        '400':
          description: Not found
          schema:
            properties:
              header:
                  $ref: '#/definitions/HeaderError'
              body:
                type: object

  /events:
    get:
      description: 'Return the upcoming events (e.g. start date >= today). Gets an array of `Event` object. Mandatory query param of **domain** determines the site / country the event belongs to.'
      parameters:
        - name: domain
          type: string
          description: 'the site the groups belongs to, example: netherlands'
          in: query
          required: true
        - name: limit
          in: query
          description: the number of desired records
          required: false
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            properties:
                header:
                  $ref: '#/definitions/HeaderSuccess'
                body:
                  type: array
                  items:
                      $ref: '#/definitions/Event'

  '/events/{UUID}':
    get:
      description: 'Get one `Event` object by specifying its UUID in the url path.'
      parameters:
        - name: UUID
          type: string
          in: path
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            properties:
                header:
                  $ref: '#/definitions/HeaderSuccess'
                data:
                  $ref: '#/definitions/Event'
        '400':
          description: Not found
          schema:
            properties:
              header:
                  $ref: '#/definitions/HeaderError'
              body:
                type: object

definitions:

  # Main models
  VolunteerLite:
    type: object
    properties:
        uuid:
          $ref: '#/definitions/UUID'
        serial:
          $ref: '#/definitions/Serial'

  Volunteer:
    type: object
    properties:
        uuid:
          $ref: '#/definitions/UUID'
        avatar:
          $ref: '#/definitions/URL'
        locations:
          type: array
          items:
            $ref: '#/definitions/LocationSimple'

  GroupLite:
    type: object
    properties:
        uuid:
          $ref: '#/definitions/UUID'
        serial:
          $ref: '#/definitions/Serial'
        name:
          type: string

  Group:
    type: object
    properties:
        uuid:
          $ref: '#/definitions/UUID'
        serial:
          $ref: '#/definitions/Serial'
        created:
          $ref: '#/definitions/DateTime'
        modified:
          $ref: '#/definitions/DateTime'
        name:
          type: string
        picture:
          $ref: '#/definitions/URL'
        mission:
          type: string
        description:
          $ref: '#/definitions/HTML'
        group_type:
          $ref: '#/definitions/GroupType'
        location:
          $ref: '#/definitions/Location'
  
  Event:
    type: object
    properties:
      uuid:
        $ref: '#/definitions/UUID'
      serial:
        $ref: '#/definitions/Serial'
      created:
        $ref: '#/definitions/DateTime'
      modified:
        $ref: '#/definitions/DateTime'
      name:
        type: string
      description:
        $ref: '#/definitions/HTML'
      picture:
        $ref: '#/definitions/URL'
      start_date:
        $ref: '#/definitions/DateTime'
      end_date:
        $ref: '#/definitions/DateTime'
      location:
        $ref: '#/definitions/Location'
      organizers:
        type: array
        items:
          $ref: '#/definitions/VolunteerLite'
      groups:
        type: array
        items:
          $ref: '#/definitions/GroupLite'
        
  
  # Complex model properties
  LocationSimple:
    type: object
    properties:
      country:
        $ref: '#/definitions/ISO_3166-1_alpha-2'

  Location:
    type: object
    properties:
      streetname:
        type: string
      postcode:
        type: string
      state:
        type: string
      city:
        type: string
      country:
        type: string
      coordinates:
        $ref: '#/definitions/Coordinates'

  GroupType:
    type: string
    enum:
      - 'Country group'
      - 'Campaign Project group'
      - 'Local group'
      - 'Discussion group'
      - 'Interest group'
      - 'Skills-based group'
      
  # Envelope
  HeaderSuccess:
    type: object
    properties:
      id:
        type: integer
        description: 'transaction nonce'
      status:
        $ref: '#/definitions/HTTP_Status'
      code:
        $ref: '#/definitions/HTTP_Code'
      resources:
        $ref: '#/definitions/ResourceType'
      pagination:
        $ref: '#/definitions/Pagination'
      error:
        type: 'null'
        
  HeaderError:
    type: object
    properties:
      id:
        type: integer
        description: 'transaction nonce'
      status:
        $ref: '#/definitions/HTTP_Status'
      code:
        $ref: '#/definitions/HTTP_Code'
      resources:
        $ref: '#/definitions/ResourceType'
      pagination:
        type: object
      error:
        type: string
        description: 'the error message'

  Pagination:
    type: object
    properties:
      limit: 
        type: integer
        description: 'the nubmer of items per page'
      page:
        type: integer
        description: 'the current page'
      total:
        type: integer
        description: 'the total number of pages'
  
  ResourceType:
    type: string
    description: 'The name of the requested object/model/resource. Plural if a collection.'
    enum:
      - 'group'
      - 'groups'
      - 'event'
      - 'events'
      - 'volunteer'
      - 'volunteers'
      
  # Default Low Level Types
  HTTP_Status:
    type: integer
    description: 'https://en.wikipedia.org/wiki/List_of_HTTP_status_codes'
  HTTP_Code:
    type: string
    description: 'https://en.wikipedia.org/wiki/List_of_HTTP_status_codes'
  Serial:
    type: string
    description: 'The primary key in Drupal, e.g the entity/node id'
  UUID:
    type: string
    description: 'Universally unique identifier in canonical format, example: de305d54-75b4-431b-adb2-eb6b9e546014'
  URL:
    type: string
    description: 'A resource location, example: https://greenwire.greenpeace.org'
  ISO_3166-1_alpha-2:
    type: string
    description: 'Country code see. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2'
  Coordinates:
    type: object
    properties:
      latitude:
        type: string
        description: 'Signed decimal format, example: 52.1234'
      longitude:
        type: string
        description: 'Signed decimal format, example -77.022223'
  DateTime:
    type: string
    description: 'The date in YYYY-MM-DD HH:MM:SS format, example: 2015-12-31 23:59:59'
  HTML:
    type: string
    description: 'A string containing sanitized HTML code'