OpenAPI 3.0.0 Specification for the Open Build Service HTTP API

by the OBS Team posted on 6th Jun 2023

Starting today, the OpenAPI Specification presented through Swagger UI becomes the official API documentation for Open Build Service 🎉

Find it at https://api.opensuse.org/apidocs/

With OpenAPI we now provide an industry standard way to maintain the specification and with Swagger UI a tool that makes consuming the documentation easier for people who want to make use of the OBS API in their code.

Now our journey to remake the API documentation has come to an end, but the most exciting journey is about to begin. Your journey to use and contribute to the OBS API documentation! 👏

Using Swagger UI

Swagger UI contains a long list of API endpoints. Un-collapse an endpoint to learn about its purpose, the parameters it uses, the possible responses, and more. At any time, you can authorize and perform a request to the API to try out the behavior of endpoints.

A picture is worth a thousand words.

Gif showing the usage of the new API documentation
Usage of the new API documentation

NOTE: The discontinued documentation will be available at https://build.opensuse.org/apidocs-old/ for a while.

Contribute to the OpenAPI Specification

First of all, you need to understand what is Swagger UI and learn the OpenAPI 3.0.0 Specification. This OpenAPI Guide is a good starting point.

Once you are familiar with the OpenAPI specification structure, you can start contributing to OBS documentation, which you can find under src/api/public/apidocs in our GitHub repository.

The main steps are:

  • Declare the new endpoint in OBS-v2.10.50.yaml. Please keep the alphabetical order.
  • Define the endpoint in YAML format under the paths/ directory.
  • Make use of the already-defined components (parameters, responses, schemas) when possible.

You can also have a look to closed pull requests to take what others did before as an example.

Enjoy the new docu 📖 and keep the feedback and contributions coming, please. It will help the whole OBS community.

How To Give Us Feedback

There are two ways to reach us:

Please note that we favor GitHub to gather feedback as it allows us to easily keep track of the discussions.

A wholehearted thank you to everyone that created the now discontinued API documentation, and also to those who have contributed and given us feedback during the development of this new documentation.

After kicking off the API documentation remake in January 2021, we’ve continued with the Build and Workers endpoints in April 2021, we followed with Sources Projects and Search endpoints in December 2021, we documented the Search endpoints in August 2022, we continued extending the Projects and Packages Sources endpoints, in March 2023 we added more for Packages and Files Sources endpoints and, at the beginning of May 2023, we worked on Comments, Status Messages and Staging endpoints. It is in June 2023 when we make the release of the new API documentation followed by the documentation of Statistics, Status Project and Status Reports endpoints, among others.