From: Stephen Finucane <stephen.finuc...@intel.com> Add specification for a REST API. It documents a number of endpoints for the following objects/models:
* Projects * People * Patches * Checks The specification is provided in OpenAPI format [1]. This specification can be used to automatically generate REST client libraries and to validate the implemented API. The API is currently read-only. It is expected that this will expanded upon as the API grows. [1] https://openapis.org/specification Signed-off-by: Stephen Finucane <stephen.finuc...@intel.com> Signed-off-by: Andy Doan <andy.d...@linaro.org> --- docs/api.yaml | 392 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 docs/api.yaml diff --git a/docs/api.yaml b/docs/api.yaml new file mode 100644 index 0000000..e2ddac5 --- /dev/null +++ b/docs/api.yaml @@ -0,0 +1,392 @@ +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: patchwork.ozlabs.org +schemes: + - https +basePath: /api/1.0 +produces: + - application/json +paths: + /: + get: + summary: API metadata. + description: | + The Metadata endpoint returns information about the API itself. + The response includes the version of the API. + responses: + 200: + description: An API metadata object. + schema: + $ref: '#/definitions/Metadata' + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /projects: + get: + summary: List available projects. + description: | + Returns information about all projects available on this patchwork + instance. The response includes the display name and other details + about each project. + parameters: + - $ref: '#/parameters/perPageParam' + - $ref: '#/parameters/pageParam' + tags: + - Projects + responses: + 200: + description: An array of projects objects. + schema: + type: array + items: + $ref: '#/definitions/Project' + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /projects/{projectId}: + get: + summary: Retrieve a project by its ID. + description: | + Returns information about a single project available on this patchwork + instance. The response includes the display name and other details + about each project. + parameters: + - $ref: '#/parameters/projectId' + tags: + - Projects + responses: + 200: + description: A project object. + schema: + $ref: '#/definitions/Project' + 404: + description: The project does not exist + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /people: + get: + summary: List available people. + description: | + Returns information about all people who have submitted patches on this + patchwork instance. The response includes the name, email and other + details about each person. + tags: + - People + parameters: + - $ref: '#/parameters/perPageParam' + - $ref: '#/parameters/pageParam' + responses: + 200: + description: An array of people objects. + schema: + type: array + items: + $ref: '#/definitions/People' + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /people/{personId}: + get: + summary: Retrieve a person by its ID. + description: | + Returns information about a single person who has submitted patches on + this patchwork instance. The response includes the name, email and + other details about each person. + parameters: + - $ref: '#/parameters/personId' + tags: + - People + responses: + 200: + description: A person object. + schema: + $ref: '#/definitions/People' + 404: + description: The project does not exist + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /patches: + get: + summary: List available patches + description: | + Returns information about all patches available on this patchwork + instance. The response includes the name, diff and other details + about each patch. + tags: + - Patches + parameters: + - $ref: '#/parameters/perPageParam' + - $ref: '#/parameters/pageParam' + - $ref: '#/parameters/sinceParam' + - $ref: '#/parameters/untilParam' + - name: project + description: project name by which to filter + in: query + type: string + - name: state + description: patch state by which to filter + in: query + type: string + - name: submitter + description: username or email of submitter by which to filter + in: query + type: string + - name: delegate + description: username or email of delegate by which to filter + in: query + type: string + responses: + 200: + description: An array of patch objects. + schema: + type: array + items: + $ref: '#/definitions/Patch' + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /patches/{patchId}: + get: + summary: Retrieve a patch 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. + parameters: + - $ref: '#/parameters/patchId' + tags: + - Patches + responses: + 200: + description: A patch object. + schema: + $ref: '#/definitions/Patch' + 404: + description: The patch does not exist + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /patches/{patchId}/checks: + get: + summary: List check statuses for given patch. + description: | + Checks store the results of any tests executed (or executing) for a + given patch. This is useful, for example, when using a continuous + integration (CI) system to test patches. + parameters: + - $ref: '#/parameters/patchId' + - $ref: '#/parameters/perPageParam' + - $ref: '#/parameters/pageParam' + tags: + - Checks + responses: + 200: + description: An array of check objects. + schema: + type: array + items: + $ref: '#/definitions/Check' + 404: + description: The patch does not exist + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' + /patches/{patchId}/check: + get: + summary: Retrieve combined check status for given patch. + description: | + Checks store the results of any tests executed (or executing) for a + given patch. This is useful, for example, when using a continuous + integration (CI) system to test patches. + parameters: + - $ref: '#/parameters/patchId' + tags: + - Checks + responses: + 200: + description: A check object. + schema: + $ref: '#/definitions/Check' + 404: + description: The patch does not exist + default: + description: Unexpected error. + schema: + $ref: '#/definitions/Error' +parameters: + # ID Parameters + projectId: + name: projectId + description: ID of project that needs to be retrieved. + in: path + type: integer + format: int32 + required: true + personId: + name: personId + description: ID of person that needs to be retrieved. + in: path + type: integer + format: int32 + required: true + patchId: + name: patchId + description: | + ID of patch that needs to be retrieved. This should be one of: a patch + ID, a patch hash, a Message-ID. + in: path + type: string + required: true + # Generic parameters + pageParam: + name: page + description: page to retrieve + in: query + type: integer + format: int32 + minimum: 1 + default: 1 + perPageParam: + name: per_page + description: custom page size + in: query + type: integer + format: int32 + minimum: 0 + maximum: 100 + default: 30 + sinceParam: + name: since + description: only items modified after this date will be returned + in: query + type: string + format: date + untilParam: + name: until + description: only items modified before this date will be returned + in: query + type: string + format: date +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. + 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: string + description: The state name of the patch. + diff: + type: string + description: Diff of patch. + mbox_url: + type: string + description: Link to the raw patch mbox contents. + People: + properties: + id: + type: integer + description: Unique identifier of person. + name: + type: string + description: Name of person. + email: + type: string + description: Email of person. + user: + type: integer + description: ID of patchwork user account connected to person. + Check: + properties: + id: + type: integer + description: Unique identifier of check. + user: + type: integer + description: ID of creator of check. + state: + type: string + description: The state of the check. + enum: + - pending + - success + - warning + - fail + url: + type: string + description: The target URL associated with this check. + description: + type: string + description: A brief description of the check. + context: + type: string + description: | + A label to discern check from checks of other testing systems. + Error: + properties: + code: + type: integer + format: int32 + message: + type: string + fields: + type: string -- 2.7.4 _______________________________________________ Patchwork mailing list Patchwork@lists.ozlabs.org https://lists.ozlabs.org/listinfo/patchwork