OpenAPI / Swagger / ReDoc

OpenAPI / Swagger / ReDoc#

Interactive API browser#

The UCS@school Kelvin REST API offers two web interfaces to explore the API graphically:

  • The Swagger UI at https://<fqdn>/ucsschool/kelvin/docs (includes a selector for v1 and v2)

  • The Swagger UI for a specific version:

    • https://<fqdn>/ucsschool/kelvin/v1/docs

    • https://<fqdn>/ucsschool/kelvin/v2/docs

  • The ReDoc UI for a specific version:

    • https://<fqdn>/ucsschool/kelvin/v1/redoc

    • https://<fqdn>/ucsschool/kelvin/v2/redoc

Both UIs are created in the browser by JavaScript code using the OpenAPI specification generated by the UCS@school Kelvin REST API server.

The OpenAPI specifications can be downloaded at:

  • https://<fqdn>/ucsschool/kelvin/v1/openapi.json

  • https://<fqdn>/ucsschool/kelvin/v2/openapi.json

Note

Version 2 of the Kelvin API behaves the same as version 1, with the exception that no hooks are executed on GET requests. This is because version 2 reads data from a separate database, which is provisioned asynchronously.

The service also provides versioned aliases that are used by the combined Swagger page:

  • https://<fqdn>/ucsschool/kelvin/openapi-v1.json

  • https://<fqdn>/ucsschool/kelvin/openapi-v2.json

The Swagger UI allows direct interaction (reading, creating users etc.) with the API server. To use it, a token must first be retrieved by clicking the Authorize button in the top right corner. In the pop-up, the username must be of a user in the group ucsschool-kelvin-rest-api-admins. The user Administrator is added to this group by default. After supplying the password and clicking the Authorize button the pop-up can be closed.

Then methods of resources can be used. After opening on one, a click on Try it out on the right side will allow to Execute the request.

Generating client code from OpenAPI schema#

Source code for UCS@school Kelvin REST API clients can be auto-generated by a number of tools. Popular open source tools that can generate source code from the servers openapi.json for over 50 programming languages are:

On this page