aboutsummaryrefslogtreecommitdiff
path: root/docs/api
Commit message (Collapse)AuthorAge
* docs: Random Python 3 updatesStephen Finucane2021-02-20
| | | | | | | Correct some documentation examples and other things to reflect the new, Python 3-only world. Signed-off-by: Stephen Finucane <stephen@that.guru>
* REST: Null out previous, current relation infoStephen Finucane2020-12-13
| | | | | | | | | | | | | | | | | These fields don't work like we expect them to. Because we're linking to a non-idempotent entity, an instance of 'relation', what we're storing in either of these fields is subject to change as patches are added and removed. This makes the information pretty much useless after the fact. It's best to just state the patch and request that people query the information themselves if necessary. We don't want to remove the field entirely from the API - that would be a truly breaking change - so instead we null it out like we do for patch tags. In a v2 API (i.e. a major version bump) we can remove this entirely. A small bug with the schema generation is corrected. Signed-off-by: Stephen Finucane <stephen@that.guru> Related: #379
* trivial: Rename 'CoverLetter' references to 'Cover'Stephen Finucane2020-04-26
| | | | | | | We're going to be doing some model surgery shortly. Do the necessary renaming of variables ahead of this. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'relations'Stephen Finucane2020-04-18
| | | | | | | | | | | Two issues here: - 'PATCH /patches/{id}' and 'PUT /patches/{id}' expect a list of integers on the 'related' field - not strings - 'GET /patches' and 'GET /patches/{id}' return a list of embedded patch objects on the 'related' field - not strings Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'events'Stephen Finucane2020-04-18
| | | | | | | | | | | | | | Four things to change here: - The response is any array that can contain any type of event, not one of them. - The 'actor' field is nullable. - The 'cover' field of the 'cover-created' event is an embedded cover letter, not a string. - The specifications for the 'current_delegate' and 'previous_delegate' fields of the 'patch-delegated' field were apparently invalid. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'comments'Stephen Finucane2020-04-18
| | | | | | | Each header in the 'headers' field can be either a string or a list value. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'patches'Stephen Finucane2020-04-18
| | | | | | | | | | Two issues: - Errors are reported as a mapping of the field name to an array of errors, not a string. - We were attempting to validate an invalid request. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'covers'Stephen Finucane2020-04-18
| | | | | | | | | | | Two issues to correct: - Each header in the 'headers' field can be either a string or a list value. - We state that the 'content' field will always have content but our tests were configuring otherwise. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'bundles'Stephen Finucane2020-04-18
| | | | | | | Errors are reported as a mapping of the field name to an array of errors, not a string. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'projects'Stephen Finucane2020-04-18
| | | | | | | | | Two issues here: - The ID in '/projects/{id}' can be either an integer or a string. - We were attempting to validate an invalid request. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Resolve issues with 'patches'Stephen Finucane2020-04-18
| | | | | | | | | | | | | | Four issues to resolve: - The 'tags' field is a key-value mapping, not an array. - Each header in the 'headers' field can be either a string or a list value. - Errors are reported as a mapping of the field name to an array of errors, not a string. - The security type information isn't complete and doesn't account for security types. Skip it for now. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Move common path parameters to parentStephen Finucane2020-04-18
| | | | | | | | | Turns out you don't have to nest common elements under individual routes [1]. Less duplication and more sensible docs = winning. [1] https://swagger.io/specification/#pathItemObject Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Make embedded fields nullable by defaultStephen Finucane2020-04-18
| | | | | | | | | | | As discussed at [1], "subtypes can add restrictions, but they cannot relax restrictions that are already in place." These fields need to be marked nullable and then "subclassed" to set non-nullability if required. [1] https://github.com/OAI/OpenAPI-Specification/issues/1368 Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Add schema validation to 'generate-schemas' toolStephen Finucane2020-04-18
| | | | | | Just to make sure we're not generating garbage. Signed-off-by: Stephen Finucane <stephen@that.guru>
* api: allow filtering patches and covers by msgidDaniel Axtens2020-04-14
| | | | | | | | | | | | | | | | | | | | In the process of fixing the previous bug, I realised that: a) /api/patches/msgid is a perfectly reasonable thing to attempt b) We have no way of finding a patch by message id in the API We can't actualy make /api/patches/msgid work because it may not be unique, but we can add a filter. I'm shoehorning this into stable/2.2, even though it's technically an API change: it's minor, not incompatible and in hindsight a glaring hole. Cc: Michael Ellerman <mpe@ellerman.id.au> Tested-by: Jeremy Kerr <jk@ozlabs.org> Reviewed-by: Andrew Donnellan <ajd@linux.ibm.com> Reviewed-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Daniel Axtens <dja@axtens.net>
* REST: Add patch relationsMete Polat2020-03-16
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | View relations and add/update/delete them as a maintainer. Maintainers can only create relations of patches which are part of a project they maintain. Because this is a writable many-many nested relationship, it behaves a little unusually. In short: - All operations use PATCH to the 'related' field of a patch - To relate a patch to another patch, say 7 to 19, either: PATCH /api/patch/7 related := [19] PATCH /api/patch/19 related := [7] - To delete a patch from a relation, say 1, 21 and 42 are related but we only want it to be 1 and 42: PATCH /api/patch/21 related := [] * You _cannot_ remove a patch from a relation by patching another patch in the relation: I'm trying to avoid read-modify-write loops. * Relations that would be left with just 1 patch are deleted. This is only ensured in the API - the admin interface will let you do this. - Break-before-make: if you have [1, 12, 24] and [7, 15, 42] and you want to end up with [1, 12, 15, 42], you have to remove 15 from the second relation first: PATCH /api/patch/1 related := [15] will fail with 409 Conflict. Instead do: PATCH /api/patch/15 related := [] PATCH /api/patch/1 related := [15] -> 200 OK, [1, 12, 15, 42] and [7, 42] are the resulting relations Signed-off-by: Mete Polat <metepolat2000@gmail.com> Signed-off-by: Stephen Finucane <stephen@that.guru> Signed-off-by: Daniel Axtens <dja@axtens.net>
* docs: Update schemas to reflect latest changes in templateStephen Finucane2020-02-27
| | | | | | | | Looks like I forgot to run the 'generate-schema' script beforehand. Fix that now. Signed-off-by: Stephen Finucane <stephen@that.guru> Fixes: cd3a2ce8 ("REST: Allow configuration of user settings via API")
* docs: Bump API version in docs to 1.2Stephen Finucane2019-12-27
| | | | Signed-off-by: Stephen Finucane <stephen@that.guru>
* REST: Allow configuration of user settings via APIStephen Finucane2019-12-24
| | | | | | Expose the embedded UserProfile field via the REST API. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Add missing series index schemaMete Polat2019-12-08
| | | | | | Fixes: 7d8e24bc84bd ("docs: Start documenting API using OpenAPI") Signed-off-by: Mete Polat <metepolat2000@gmail.com> Reviewed-by: Stephen Finucane <stephen@that.guru>
* REST: Add 'actor' field to '/events' modelJohan Herland2019-12-01
| | | | | | | | Signed-off-by: Johan Herland <johan@herland.net> Reviewed-by: Stephen Finucane <stephen@that.guru> Acked-by: Daniel Axtens <dja@axtens.net> Cc: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Closes: #73
* docs: Only include 'order' filter in '/events/' for v1.2+Stephen Finucane2019-11-30
| | | | | | | | Even though we don't actually version this thing, don't document for older versions of the API lest people using older deployments get confused. Signed-off-by: Stephen Finucane <stephen@that.guru>
* api: support filtering patches by hashDaniel Axtens2019-11-30
| | | | | | | | | | | | | | | | | This is a feature that the XML-RPC API has, and which is used in the wild [1], so support it in the REST API. I tried to version the new filter field, but it's not at all clear how to do this with django-filters. The best way I could find requires manually manipulating request.GET, which seems to defeat the point of django-filters. So document it for 1.2, and have it work on older versions as an undocumented feature. [1] https://git.kernel.org/pub/scm/linux/kernel/git/mricon/korg-helpers.git/tree/git-patchwork-bot.py?id=104e7374e1be8458e6d2e82478625a7bf8c822ff Cc: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Signed-off-by: Daniel Axtens <dja@axtens.net> Acked-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
* REST: Allow creating, updating, deleting of bundlesStephen Finucane2019-10-17
| | | | | | | | | | Allow users to create a new bundle, change the name, public flag and patches of an existing bundle, and delete an existing bundle. Some small nits with existing tests are resolved. Signed-off-by: Stephen Finucane <stephen@that.guru> Closes: #316
* docs: Rename and make 'generate_schema' executableStephen Finucane2019-10-05
| | | | | | A small Python 3 issue is resolved. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Use '>=' in OpenAPI schema templateStephen Finucane2019-09-09
| | | | | | | This is consistent with how we're doing checks for v1.2 and reads a little better, IMO. Signed-off-by: Stephen Finucane <stephen@that.guru>
* models: Add commit_url_format to ProjectMichael Ellerman2019-08-30
| | | | | | | | | | | | Add a new field to Project, commit_url_format, which specifies a format string that can be used to generate a link to a particular commit for a project. This is used in the display of a patch, to render the patch's commit as a clickable link back to the commit on the SCM website. Signed-off-by: Michael Ellerman <mpe@ellerman.id.au> Signed-off-by: Daniel Axtens <dja@axtens.net>
* docs: Add API v1.2Andrew Donnellan2019-08-22
| | | | | | | Add API v1.2, including the new fields for list archive URLs. Signed-off-by: Andrew Donnellan <ajd@linux.ibm.com> Signed-off-by: Daniel Axtens <dja@axtens.net>
* REST: A check must specify a stateDaniel Axtens2019-04-30
| | | | | | | | | | The Ozlabs crew noticed that a check without a state caused a KeyError in data['state']. Mark state as mandatory, check for it, and add a test. Reported-by: Russell Currey <ruscur@russell.cc> Reported-by: Jeremy Kerr <jk@ozlabs.org> Signed-off-by: Daniel Axtens <dja@axtens.net>
* docs: Fix user's profile urlAli Alnubani2019-02-25
| | | | | Signed-off-by: Ali Alnubani <alialnu@mellanox.com> Reviewed-by: Stephen Finucane <stephen@that.guru>
* docs: Integrate API schema into docsStephen Finucane2019-01-29
| | | | | | | | This takes advantage of the sphinxcontrib-openapi Sphinx extension, which allows us to embed the REST API documentation into our docs quite nicely. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Move REST API guide to subfolderStephen Finucane2019-01-29
| | | | | | | | | | We're going to dramatically expand these docs, so let's set up room to do so. This shouldn't break any links as we're using 'htmldir' output on ReadTheDocs. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Detail JSON PATCH requestsStephen Finucane2018-12-25
| | | | | | | | It turns out it is possible to make PATCH requests with JSON bodies rather than form-encoded data - you just need to include a Content-Type header. Document this. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Reformat schemasStephen Finucane2018-12-24
| | | | | | Tested using 'yamllint'. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Add parameter descriptions, typesStephen Finucane2018-12-24
| | | | Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Move 'parameter.schema.description' to 'parameter'Stephen Finucane2018-12-24
| | | | | | | | | As noted in a bug against the spec [1], there is some duplication here. Go with the more obvious path until that confusion is cleared up. [1] https://github.com/OAI/OpenAPI-Specification/issues/1788 Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Store versioned OpenAPI schemasStephen Finucane2018-12-22
| | | | Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Make API document versionedStephen Finucane2018-12-22
| | | | | | | | | | | | | | | OpenAPI doesn't appear to support versioning natively, suggesting instead that separate documents are kept. Rather than doing this manually, let's use a templating tool - Jinja2, in this case - to generate these document for us from a single master document. Note that while we can now auto-generate these whenever we need them (and we tend to avoid storing auto-generated assets in VCS), these change so rarely that it's easier to just store them. This also means we can reference the schemas themselves online. We do this in a following change. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/events' resourceStephen Finucane2018-12-22
| | | | | | | | This is the final resource to document and also the most complicated, on account of the polymorphism of the responses. However, with this done, our first pass at an OpenAPI 3.0 schema is completed. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/patches/{patch_id}/checks' resourceStephen Finucane2018-12-22
| | | | Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/patch/{id}/comments' resourceStephen Finucane2018-12-22
| | | | Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/covers/{id}/comments' resourceStephen Finucane2018-12-22
| | | | | | | Our first nested resource. Nothing too weird here though, save for the raising of a HTTP 404 on a list resource (due to a missing patch). Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/series' resourceStephen Finucane2018-12-22
| | | | Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/patches' resourceStephen Finucane2018-12-22
| | | | | | The big one (TM). Nothing too odd here though. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/covers' resourceStephen Finucane2018-12-22
| | | | | | | Again, we're adding embedded serializers before the main resource but that will come. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/bundles' resourceStephen Finucane2018-12-22
| | | | | | | | | This one's a little unusual too, in that we provide the embedded serializer for resources we haven't defined the end resource for. That's necessary in general, due to recursive references in the API (series-patch, patch-series etc.) so might as well embrace it early. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/projects' resourceStephen Finucane2018-12-22
| | | | | | This one's pretty straightforward. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/people' resourceStephen Finucane2018-12-22
| | | | | | | | This introduces our first use of embedded serializers, which are separate models from the main ones. Other than that, this is pretty standard. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Document the '/users' resourceStephen Finucane2018-12-22
| | | | | | | This introduces our first use of parameters, both in the path and the query. The latter are extracted out as they'll be used by later changes. Signed-off-by: Stephen Finucane <stephen@that.guru>
* docs: Start documenting API using OpenAPIStephen Finucane2018-12-22
| | | | | | | | | | | | | | | When the REST API was first added, we attempted to document it using OpenAPI 2.0 (formerly Swagger). This was mostly never completed because (a) it was really tedious and (b) no one was that bothered. However, as we expand the range of clients for the REST API, having a well documented API becomes more and more of an asset. Start doing this by adding a brand new schema, this time using OpenAPI. This will entirely replace the older schema and, as such, is namespaced separately. We start by documenting '/' (i.e. the index) page and will add additional resources as we go. Signed-off-by: Stephen Finucane <stephen@that.guru>
generated by cgit v1.2.3 (git 2.45.0) at 2024-11-24 12:47:33 +0000