Make OpenAPI definition document (previously known as Swagger specification) available for Sierra's APIs
There SHOULD be an OpenAPI definition document available for Sierra's APIs via Swagger, but currently, there is not.
The OpenAPI definition document (https://swagger.io/specification/) is a standardized format for describing the structure and behavior of an API. It is a machine-readable document, usually written in JSON or YAML, that provides a comprehensive blueprint of an API's endpoints, operations, input/output parameters, response formats, authentication methods, and other essential details.
For comparison, here is an example for the Polaris API / Swagger install (on an iii training server):
https://polaris-training.polarislibrary.com/PAPIService/swagger/v1/swagger.json
Benefits of an OpenAPI Definition Document:
* Standardization: Provides a consistent format for describing APIs.
* Documentation: Automatically generates interactive API documentation (e.g., Swagger UI).
* Client Generation: Allows the generation of client libraries in various programming languages.
* Validation: Ensures requests and responses conform to the defined schema.
* Interoperability: Facilitates integration between different systems by providing a clear API contract.
Access to this document is ESSENTIAL for development and integration purposes, especially when using tools like Python and other programming languages with the APIs.
Having this document for Sierra would significantly enhance the development experience and improve integration capabilities, and should be considered essential.
-
Ray Voelker commented
@David Jones ... I think that an updated version of Swagger would be a great start, and maybe that's all that's really needed!
-
Jeremy Goldstein commented
This really would make working with the APIs a lot easier an improved prospect and be a big step toward fulfilling the promise of opening up the system.
-
David Jones commented
Are you just asking for a newer version of the Swagger/OpenAPI JSON than what is already available? https://sandbox.iii.com/iii/sierra-api/docs -> https://sandbox.iii.com/iii/sierra-api/docs/v6/bibs
-
Jennifer Schmidt commented
It sounds as though this is needed not just for developers in the ILS community but also for third party vendors libraries work with to maximize Sierra functionality. This would make things more transparent and improve capabilities for libraries!
-
Kimberly Allen commented
I don't play in this area, but this would be essential information for folks who do.
-
AdminJulie Cole (Admin, Innovative) commented
The API we use for Talis Reading Lists uses this standard and I have found it very useful when requesting and formatting the data that gets returned.
-
Lloyd Chittenden commented
I don't know anything about this at all, but it sounds like an important best practice.