[RFC] docs: Add prototype API specification

[Andy Doan]

On 03/25/2016 11:12 AM, Stephen Finucane wrote:
> Add specification for a REST API. It documents a number of endpoints
> for the following objects/models:
>
> * Projects
> * People
> * Patches
> * Bundles
> * Checks

Too bad DRF or Swagger can't somehow work with each other so we don't 
have to remember these definitions live in 2 places.

One general comment: Every endpoint includes two query parameters:
  - $ref: '#/parameters/sinceParam'
  - $ref: '#/parameters/untilParam'

I'm not sure we have the information available to handle such requests 
for most of our objects?

> diff --git a/docs/api.yaml b/docs/api.yaml

> +swagger: '2.0'
> +info:
> +  title: Patchwork API
> +  description: |
> +    Patchwork is a web-based patch tracking system designed to facilitate the
> +    contribution and management of contributions to an open-source project.
> +  version: "1.0.0"
> +host: api.uber.com

not sure what that should point to?

> +schemes:
> +  - https
> +basePath: /v1

I liked "v1" also. Freedesktop is using 1.0 in their deployment. Do we 
want to try and make this somewhat compatible with them? Or maybe v1 
will make it more obvious this isn't the exact same thing

> +  /people:
> +  /people/{personId}:

Just a security question: should we require an authenticated user to 
query other people?

> +  /people/{personId}/bundles:

Should probably denote this only works if you are authenticated as 
"personId". Launchpad, used to have a handy mechanism in their API's 
where you could do "people/+me/bundles" so you don't have to remember 
your ID.

> +  /patches/{patchId}.mbox:
> +    get:
> +      summary: Retrieve a patch in mbox format by its ID.
> +      description: |
> +        Returns information about a single patch available on this patchwork
> +        instance. The response includes the name, diff and other details
> +        about each patch. Patch is formatted in mbox format.

s/each patch/the patch/

> +      parameters:
> +        - $ref: '#/parameters/patchId'
> +      tags:
> +        - Patches
> +      responses:
> +        200:
> +          description: A patch object.
> +          schema:
> +            $ref: '#/definitions/Patch'

Is that the proper response for an "mbox"? Should ie - rather than 
"diff", should it return "mail" or something.

> +definitions:
> +  Metadata:
> +    properties:
> +      revision:
> +        type: integer
> +        description: Revision of the API.
> +  Project:
> +    properties:
> +      id:
> +        type: integer
> +        description: Unique identifier of project.
> +      name:
> +        type: string
> +        description: Name of project.
> +      linkname:
> +        type: string
> +        description: Link name of project.
> +      listemail:
> +        type: string
> +        description: Mailing list email address for project.
> +      web_url:
> +        type: string
> +        description: Upstream website for project.
> +      scm_url:
> +        type: string
> +        description: SCM "clone" url for project.
> +      webscm_url:
> +        type: string
> +        description: Web browsable URL for project.

do we want to include "send_notifications" and "use_tags"?

> +  Patch:
> +    properties:
> +      id:
> +        type: integer
> +        description: Unique identifier of patch.
> +      project:
> +        type: integer
> +        description: Project ID of patch.
> +      name:
> +        type: string
> +        description: Name of patch.
> +      date:
> +        type: string
> +        format: date-time
> +        description: Submission date of patch.
> +      submitter:
> +        type: integer
> +        description: ID of submitter of patch.
> +      delegate:
> +        type: integer
> +        description: ID of delegate assigned to patch.
> +      state:
> +        type: integer
> +        description: ID of state of patch.
> +      diff:
> +        type: string
> +        description: Diff of patch.

Do we need "tags", "commit_ref", "pull_url", or "archived"?

Also - will we want to be able to retrieve Comments for a Patch?