todo-list-with-id.yaml

swagger: '2.0'
info:
  title: Todo List API
  version: initial
consumes:
- application/json
produces:
- application/json
- text/html
x-interfaces:
  Item: &Item
    get:
      description: Retrieve an Item
      parameters:
      - $ref: '#/parameters/Accept'
      responses:
        '200':
          description: successful
          headers:
            Content-Location:
              description: perma-link URL of resource
              type: string
            Content-Type:
              description: The media type of the returned body
              type: string
            ETag:
              description: this value must be echoed in the If-Match header of every
                PATCH or PUT
              type: string
          schema:
            $ref: '#/definitions/Item'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '406':
          $ref: '#/responses/406'
        default:
          $ref: '#/responses/default'
    patch:
      consumes:
      - application/merge-patch+json
      description: Update an Item entity
      parameters:
      - $ref: '#/parameters/If-Match'
      - description: The subset of properties of the Item being updated
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/Item'
      responses:
        '200':
          description: successful
          headers:
            Content-Location:
              description: perma-link URL of resource
              type: string
            Content-Type:
              description: The media type of the returned body
              type: string
            ETag:
              description: this value must be echoed in the If-Match header of every
                PATCH or PUT
              type: string
          schema:
            $ref: '#/definitions/Item'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '406':
          $ref: '#/responses/406'
        '409':
          $ref: '#/responses/409'
        default:
          $ref: '#/responses/default'
    delete:
      description: Delete an Item
      responses:
        '200':
          description: successful
          headers:
            Content-Location:
              description: perma-link URL of resource
              type: string
            Content-Type:
              description: The media type of the returned body
              type: string
            ETag:
              description: this value must be echoed in the If-Match header of every
                PATCH or PUT
              type: string
          schema:
            $ref: '#/definitions/Item'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '406':
          $ref: '#/responses/406'
        default:
          $ref: '#/responses/default'
    head:
      description: retrieve HEAD
      responses:
        '200':
          $ref: '#/responses/standard_200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    options:
      description: Retrieve OPTIONS
      parameters:
      - $ref: '#/parameters/Access-Control-Request-Method'
      - $ref: '#/parameters/Access-Control-Request-Headers'
      responses:
        '200':
          $ref: '#/responses/options_200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    x-id: Item
  TodoList:
    get:
      description: Retrieve a TodoList
      parameters:
      - $ref: '#/parameters/Accept'
      responses:
        '200':
          description: successful
          headers:
            Content-Location:
              description: perma-link URL of resource
              type: string
            Content-Type:
              description: The media type of the returned body
              type: string
            ETag:
              description: this value must be echoed in the If-Match header of every
                PATCH or PUT
              type: string
          schema:
            $ref: '#/definitions/TodoList'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '406':
          $ref: '#/responses/406'
        default:
          $ref: '#/responses/default'
    head:
      description: retrieve HEAD
      responses:
        '200':
          $ref: '#/responses/standard_200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    options:
      description: Retrieve OPTIONS
      parameters:
      - $ref: '#/parameters/Access-Control-Request-Method'
      - $ref: '#/parameters/Access-Control-Request-Headers'
      responses:
        '200':
          $ref: '#/responses/options_200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    x-id: TodoList
  TodoList.todos:
    get:
      responses:
        '200':
          description: description
          headers:
            Content-Location:
              description: perma-link URL of collection
              type: string
            Content-Type:
              description: The media type of the returned body
              type: string
          schema:
            $ref: '#/definitions/Collection'
        '303':
          $ref: '#/responses/303'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '406':
          $ref: '#/responses/406'
        default:
          $ref: '#/responses/default'
    post:
      description: Create a new Item
      parameters:
      - description: The representation of the new Item being created
        in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/Item'
      - description: The media type of the body
        in: header
        name: Content-Type
        required: true
        type: string
      responses:
        '201':
          description: Created new Item
          headers:
            Content-Type:
              description: The media type of the returned body
              type: string
            ETag:
              description: Value of ETag required for subsequent updates
              type: string
            Location:
              description: perma-link URL of newly-created Item
              type: string
          schema:
            $ref: '#/definitions/Item'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '406':
          $ref: '#/responses/406'
        default:
          $ref: '#/responses/default'
    head:
      description: Retrieve HEAD
      responses:
        '200':
          $ref: '#/responses/standard_200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    options:
      description: Retrieve OPTIONS
      parameters:
      - $ref: '#/parameters/Access-Control-Request-Method'
      - $ref: '#/parameters/Access-Control-Request-Headers'
      responses:
        '200':
          $ref: '#/responses/options_200'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    x-id: TodoList.todos
x-templates:
  '{TodoList-URL}':
    $ref: '#/x-interfaces/TodoList'
  '{TodoList-URL}/todos':
    $ref: '#/x-interfaces/TodoList.todos'
  '{TodoList-URL}/todos/{id}':
    parameters:
    - in: path
      name: id
      required: true
      type: string
    <<: *Item
paths:
  /:
    $ref: '#/x-templates/{TodoList-URL}'
  /todos:
    $ref: '#/x-templates/{TodoList-URL}~1todos'
  /todos/{id}:
    $ref: '#/x-templates/{TodoList-URL}~1todos~1{id}'
definitions:
  TodoList:
    readOnly: true
    properties:
      todos:
        type: string
        format: uri
        x-interface: '#/x-interfaces/TodoList.todos'
    x-interface: '#/x-interfaces/TodoList'
  Item:
    properties:
      id:
        type: string
        readOnly: true
      description:
        type: string
      due:
        type: string
        format: date-time
    x-interface: '#/x-interfaces/Item'
  Collection:
    readOnly: true
    properties:
      contents:
        type: array
        items:
          $ref: '#/definitions/Item'
parameters:
  Accept:
    description: specifies the requested media type - required
    in: header
    name: Accept
    required: true
    type: string
  Access-Control-Request-Headers:
    description: specifies the custom headers the client wishes to use
    in: header
    name: Access-Control-Request-Headers
    required: true
    type: string
  Access-Control-Request-Method:
    description: specifies the method the client wishes to use
    in: header
    name: Access-Control-Request-Method
    required: true
    type: string
  If-Match:
    description: specifies the last known ETag value of the resource being modified
    in: header
    name: If-Match
    required: true
    type: string
responses:
  '303':
    description: See other. Server is redirecting client to a different resource
    headers:
      Location:
        description: URL of other resource
        type: string
  '400':
    description: Bad Request. Client request in error
    schema: {}
  '401':
    description: Unauthorized. Client authentication token missing from request
    schema: {}
  '403':
    description: Forbidden. Client authentication token does not permit this method
      on this resource
    schema: {}
  '404':
    description: Not Found. Resource not found
    schema: {}
  '406':
    description: Not Acceptable. Requested media type not available
    schema: {}
  '409':
    description: Conflict. Value provided in If-Match header does not match current
      ETag value of resource
    schema: {}
  default:
    description: 5xx errors and other stuff
    schema: {}
  options_200:
    description: successful
    headers:
      Access-Control-Allow-Headers:
        description: headers allowed
        type: string
      Access-Control-Allow-Methods:
        description: methods allowed
        type: string
      Access-Control-Allow-Origin:
        description: origins allowed
        type: string
      Access-Control-Max-Age:
        description: length of time response can be cached
        type: string
  standard_200:
    description: successful
    headers:
      Content-Location:
        description: perma-link URL of resource
        type: string
      Content-Type:
        description: The media type of the returned body
        type: string
      ETag:
        description: this value must be echoed in the If-Match header of every PATCH
          or PUT
        type: string