swagger: '2.0'
info:
  title: ORB API
  description: REST Interface to recipe information
  version: 1.0.0
schemes:
  - https
basePath: /orb/rest/api
produces:
  - application/json
paths:
  /token:
    get:
      tags:
        - auth
      summary: Request API Token
      description: |
        Request an API token to use when issuing queries to the REST API. When
        calling the API programmatically, include this token in the
        'Private-Token' request header field with each request made. Note that
        each call to this endpoint will generate a new API token, invalidating
        any token previously associated with your account.


        **Required capabilities**: api.use
      responses:
        '200':
          description: An API Token
          schema:
            $ref: '#/definitions/Token'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /ingredients:
    get:
      tags:
        - ingredients
      summary: Fetch the list of ingredients
      description: |
        Retrieve the list of ingredients defined in the system.
      parameters:
        - name: term
          description: A partial name to search for ingredients with
          in: query
          type: string
          required: false
      responses:
        '200':
          description: A list of ingredients
          schema:
            $ref: '#/definitions/Ingredients'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /recipes:
    get:
      tags:
        - recipe
      summary: Fetch a list of recipes defined in the system
      description: |
        Retrieve the list of recipes defined in the system.
      parameters:
        - name: name
          description: A name to search for recipes with
          in: query
          type: string
          required: false
      responses:
        '200':
          description: A list of recipes
          schema:
            $ref: '#/definitions/Recipes'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /tags:
    get:
      tags:
        - tags
      summary: Fetch a list of tags defined in the system
      description: |
        Retrieve the list of tags defined in the system.
      parameters:
        - name: term
          description: A partial name to search for tags with
          in: query
          type: string
          required: false
      responses:
        '200':
          description: A list of tags
          schema:
            $ref: '#/definitions/Tags'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/menus/{name}':
    get:
      tags:
        - menus
      summary: Fetch the information for the specified menu
      description: |
        This will return the information for the specified menu.
      parameters: 
        - name: name
          description: The name of the menu to return the data for, or 'active' to retrieve the user's currently active menu
          in: path
          type: string
          required: true
          default: 'active'
      responses: 
        '200':
          description: The details of the menu
          schema:
            $ref: '#/definitions/Menu'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      tags:
        - menus
      summary: Create a menu with the specified name
      description: |
        This will create the menu, set it as the user's active menu, and return the information for the menu.
      parameters: 
        - name: name
          description: The name of the menu to create
          in: path
          type: string
          required: true
      responses: 
        '200':
          description: The details of the menu
          schema:
            $ref: '#/definitions/Menu'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/menus/{name}/stage/{identifier}':
    put:
      tags:
        - menus
      summary: Stage a recipe on the specified menu
      description: This will stage the recipe identified by {identifier} on the specified menu. If the menu name is 'current', the user's current menu is used.
      parameters: 
        - name: name
          description: The name of the menu to return the data for, or 'active' to retrieve the user's currently active menu
          in: path
          type: string
          required: true
          default: 'active'
        - name: identifier
          description: The identifier for the recipe - generally the recipe ID
          in: path
          type: string
          required: true
      responses: 
        '200':
          description: The details of the menu
          schema:
            $ref: '#/definitions/Menu'
        '403':
          description: Permission error
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Ingredient:
    type: object
    properties:
      id:
        type: number
        description: The ID of the ingredient in the system
      text:
        type: string
        description: The ingredient name
  Ingredients:
    type: array
    items:
      $ref: '#/definitions/Ingredient'
  Recipe:
    type: object
  Recipes:
    type: array
    items:
      $ref: '#/definitions/Recipe'
  Tag:
    type: object
    properties:
      id:
        type: number
        description: The ID of the tag in the system
      text:
        type: string
        description: The tag name
  Tags:
    type: array
    items:
      $ref: '#/definitions/Tag'
  Menu:
    type: object
    properties:
      name:
        type: string
        description: The name of the menu
  Token:
    type: object
    properties:
      token:
        type: string
        description: Unique identifier to pass in the Private-Token header.
  Error:
    type: object
    properties:
      code:
        type: string
        description: A short identifying code for the error type
      message:
        type: string
        description: A longer message explaining the cause of the error