From 6a446c3826e2f93174368b3a429ae79372980faf Mon Sep 17 00:00:00 2001 From: Tomas Cohen Arazi Date: Thu, 27 May 2021 17:02:35 -0300 Subject: [PATCH] Bug 28412: Add information about supported authentication methods This patch adds an initial text explaining the valid authentication mechanisms Koha has for the API. My first approach included information about the controlling sysprefs, but I decided to remove it, as it is not usual for API consumers to be presented such detailed internal information which is probably confusing. We could add a link to the manual, but that's not the point I think. I've added an entry about error messages and how we thougth about them. It is copied from Docker Engine's API docs. This is my 2 cents. Signed-off-by: Kyle M Hall --- api/v1/swagger/swagger.yaml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml index 2e4e9bc09f..19c7959ad0 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -23,6 +23,31 @@ info: This API is documented in **OpenAPI format**. + ## Authentication + + The API supports the following authentication mechanisms + + * Basic authentication + * OAuth2 (client credentials grant) + * Cookie-based + + Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled + on the system preferences. + + ## Errors + + The API uses standard HTTP status codes to indicate the success or failure + of the API call. The body of the response will be JSON in the following format: + + ``` + { + "error": "patron not found" + } + ``` + + Note: Some routes might offer additional attributes in their error responses but that's + subject to change and thus not documented. + ## Special headers ### x-koha-library -- 2.30.1 (Apple Git-130)