aboutsummaryrefslogtreecommitdiff
path: root/docs/api
Commit message (Expand)AuthorAge
* docs: Random Python 3 updates•••Correct some documentation examples and other things to reflect the new, Python 3-only world. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2021-02-20
* REST: Null out previous, current relation info•••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 Stephen Finucane2020-12-13
* trivial: Rename 'CoverLetter' references to 'Cover'•••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> Stephen Finucane2020-04-26
* docs: Resolve issues with 'relations'•••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> Stephen Finucane2020-04-18
* docs: Resolve issues with 'events'•••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> Stephen Finucane2020-04-18
* docs: Resolve issues with 'comments'•••Each header in the 'headers' field can be either a string or a list value. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2020-04-18
* docs: Resolve issues with 'patches'•••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> Stephen Finucane2020-04-18
* docs: Resolve issues with 'covers'•••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> Stephen Finucane2020-04-18
* docs: Resolve issues with 'bundles'•••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> Stephen Finucane2020-04-18
* docs: Resolve issues with 'projects'•••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> Stephen Finucane2020-04-18
* docs: Resolve issues with 'patches'•••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> Stephen Finucane2020-04-18
* docs: Move common path parameters to parent•••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> Stephen Finucane2020-04-18
* docs: Make embedded fields nullable by default•••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> Stephen Finucane2020-04-18
* docs: Add schema validation to 'generate-schemas' tool•••Just to make sure we're not generating garbage. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2020-04-18
* api: allow filtering patches and covers by msgid•••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> Daniel Axtens2020-04-14
* REST: Add patch relations•••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> Mete Polat2020-03-16
* docs: Update schemas to reflect latest changes in template•••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") Stephen Finucane2020-02-27
* docs: Bump API version in docs to 1.2•••Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2019-12-27
* REST: Allow configuration of user settings via API•••Expose the embedded UserProfile field via the REST API. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2019-12-24
* docs: Add missing series index schema•••Fixes: 7d8e24bc84bd ("docs: Start documenting API using OpenAPI") Signed-off-by: Mete Polat <metepolat2000@gmail.com> Reviewed-by: Stephen Finucane <stephen@that.guru> Mete Polat2019-12-08
* REST: Add 'actor' field to '/events' model•••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 Johan Herland2019-12-01
* docs: Only include 'order' filter in '/events/' for v1.2+•••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> Stephen Finucane2019-11-30
* api: support filtering patches by hash•••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> Daniel Axtens2019-11-30
* REST: Allow creating, updating, deleting of bundles•••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 Stephen Finucane2019-10-17
* docs: Rename and make 'generate_schema' executable•••A small Python 3 issue is resolved. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2019-10-05
* docs: Use '>=' in OpenAPI schema template•••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> Stephen Finucane2019-09-09
* models: Add commit_url_format to Project•••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> Michael Ellerman2019-08-30
* docs: Add API v1.2•••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> Andrew Donnellan2019-08-22
* REST: A check must specify a state•••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> Daniel Axtens2019-04-30
* docs: Fix user's profile url•••Signed-off-by: Ali Alnubani <alialnu@mellanox.com> Reviewed-by: Stephen Finucane <stephen@that.guru> Ali Alnubani2019-02-25
* docs: Integrate API schema into docs•••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> Stephen Finucane2019-01-29
* docs: Move REST API guide to subfolder•••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> Stephen Finucane2019-01-29
* docs: Detail JSON PATCH requests•••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> Stephen Finucane2018-12-25
* docs: Reformat schemas•••Tested using 'yamllint'. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-24
* docs: Add parameter descriptions, types•••Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-24
* docs: Move 'parameter.schema.description' to 'parameter'•••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> Stephen Finucane2018-12-24
* docs: Store versioned OpenAPI schemas•••Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Make API document versioned•••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> Stephen Finucane2018-12-22
* docs: Document the '/events' resource•••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> Stephen Finucane2018-12-22
* docs: Document the '/patches/{patch_id}/checks' resource•••Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Document the '/patch/{id}/comments' resource•••Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Document the '/covers/{id}/comments' resource•••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> Stephen Finucane2018-12-22
* docs: Document the '/series' resource•••Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Document the '/patches' resource•••The big one (TM). Nothing too odd here though. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Document the '/covers' resource•••Again, we're adding embedded serializers before the main resource but that will come. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Document the '/bundles' resource•••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> Stephen Finucane2018-12-22
* docs: Document the '/projects' resource•••This one's pretty straightforward. Signed-off-by: Stephen Finucane <stephen@that.guru> Stephen Finucane2018-12-22
* docs: Document the '/people' resource•••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> Stephen Finucane2018-12-22
* docs: Document the '/users' resource•••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> Stephen Finucane2018-12-22
* docs: Start documenting API using OpenAPI•••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> Stephen Finucane2018-12-22
generated by cgit v1.2.3 (git 2.48.1) at 2025-04-08 18:46:31 +0000