From c0eb930e98428d1e96a7cb3a33debfd8038a78fe Mon Sep 17 00:00:00 2001 From: Martin Renvoize Date: Mon, 23 Oct 2023 16:19:18 +0100 Subject: [PATCH] Bug 29523: (follow-up) Adding documentation to swagger.yaml Signed-off-by: Martin Renvoize Signed-off-by: Marcel de Rooy Signed-off-by: Tomas Cohen Arazi --- api/v1/swagger/swagger.yaml | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/api/v1/swagger/swagger.yaml b/api/v1/swagger/swagger.yaml index 351f796c56..cdca970837 100644 --- a/api/v1/swagger/swagger.yaml +++ b/api/v1/swagger/swagger.yaml @@ -767,9 +767,20 @@ info: name: Koha Development Team url: https://koha-community.org/ description: | - ## Introduction + ## Background - This API is documented in **OpenAPI format**. + The API supports two sets of endpoints, one targetted at library staff and the other at at library users. + + Those endpoints under the `/public` path are aimed at delivering functionality tailored to library users and offer + a more restricted set of functions, overrides and data in thier responses for data privacy and library policy + reasons. Many of these endpoints do not require authentication for fetching public data, though an authenticated + session will expose additional options and allow users to see more data where it is part of their own record. + + All other endpoints are targetted at the staff interface level and allow for additional functionality and a more + unrestricted view of data. These endpoints, however, have a level of redaction built in for resources that the + api consumer should not have access to. For example, user data for users who do not belong to the same library + or library group of your api user will be reduced to just minimum neccesary for a valid response. Object keys will + be consistent for all responses, but their values may be removed depending on access. ## Authentication @@ -782,6 +793,14 @@ info: Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled by system preferences. + ## Authorization + + The API uses existing user profiles to restrict access to resources based on user permissions and the library the + API user is assigned to. This may result, at times, in resources being returned in a redacted form with all keys + present but sensative values nulled. + + We do not yet support OAuth Scopes or the Authorization Code grant flow. + ## Errors The API uses standard HTTP status codes to indicate the success or failure -- 2.39.5