From f10bcb49d17234dc52c8b67a7b7fd1796ab6f435 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Thu, 20 Sep 2018 12:40:12 -0700 Subject: work in progress on guide (mdbook) --- guide/src/http_api.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 guide/src/http_api.md (limited to 'guide/src/http_api.md') diff --git a/guide/src/http_api.md b/guide/src/http_api.md new file mode 100644 index 00000000..5b38339f --- /dev/null +++ b/guide/src/http_api.md @@ -0,0 +1,56 @@ +# REST API + +The fatcat HTTP API is mostly a classic REST CRUD (Create, Read, Update, +Delete) API, with a few twists. + +A declarative specification of all API endpoints, JSON data models, and +response types is available in OpenAPI 2.0 format. Code generation tools are +used to generate both server-side type-safe endpoint routes and client-side +libraries. Auto-generated reference documentation is, for now, available at +. + +All API traffic is over HTTPS; there is no insecure HTTP endpoint, even for +read-only operations. To start, all endpoints accept and return only JSON +serialized content. + +## Editgroups + +All mutating entity operations (create, update, delete) accept an +`editgroup_id` query parameter. If the parameter isn't set, the editor's +"currently active" editgroup will be used, or a new editgroup will be created +from scratch. It's generally preferable to manually create an editgroup and use +the `id` in edit requests; the allows appropriate metadata to be set. The +"currently active" editgroup behavior may be removed in the future. + +## Sub-Entity Expansion + +To reduce the need for multiple GET queries when looking for common related +metadata, it is possible to include linked entities in responses using the +`expand` query parameter. For example, by default the `release` model only +includes an optional `container_id` field which points to a container entity. +If the `expand` parameter is set: + + https://api.qa.fatcat.wiki/v0/release/aaaaaaaaaaaaarceaaaaaaaaam?expand=container + +Then the full container model will be included under the `container` field. +Multiple expand parameters can be passed, comma-separated. + +## Authentication and Authorization + +There are two editor types: bots and humans. Additionally, either type of +editor may have additional privileges which allow them to, eg, directly accept +editgroups (as opposed to submitting edits for review). + +All mutating API calls (POST, PUT, DELETE HTTP verbs) require token-based +authentication using an HTTP Bearer token. If you can't generate such a token +from the web interface (because that feature hasn't been implemented), look for +a public demo token for experimentation, or ask an administrator for a token. + +## QA Instance + +The intent is to run a public "sandbox" QA instance of the catalog, using a +subset of the full catalog, running the most recent development branch of the +API specification. This instance can be used by developers for prototyping and +experimentation, though note that all data is periodically wiped, and this +endpoint is more likely to have bugs or be offline. + -- cgit v1.2.3