OBS API

Api Doc

We document our API with the tool restility. There is one api.txt file in open-build-service/docs/api/api with the following format.

Headings

= Heading Level 1
== Heading Level 2

Content

GET /about

  Get information about API.

XmlBody: about
XmlResult: about

Define a route with the HTTP verb in the front.

GET /about

Add some description text (indented by 2 spaces).

  Description of the route.

Add an example XML (XmlResult) which is just to provide the user an example. This is just a file in the same directory as api.txt called about.xml in this case.

XmlResult: about

Add a XML schema file (XmlBody) in RelaxNG or XML Schema which is used for validating the XML received and sent. This is just a file in the same directory as api.txt called about.rng or about.xsd.

XmlBody: about

Building the API docu

In development environment, these are the steps to add and build the API docu:

• Update the text in api.txt.
• Access the frontend container. For example by docker compose exec frontend /bin/bash -l after running docker compose up.
• Move to open-build-service/docs/api inside the container.
• Call make. If the syntax is ok then the HTML output, including an index file, will be generated in docs/api/html/.

Enabling API docu in development environment

First add the location of the API Doc files in config/options.yml as follows and restart the server.

development:                                                                                                                                          
  <<: *default
  apidocs_location: /obs/docs/api/html

The API documentation will be available in localhost:3000/apidocs/index.

Don't forget to run make every time you change something in api.txt to generate the up-to-date HTML file, as explained before.

Changing the OBS API

NOTE: This is an unopinionated summary of how we handle changes in the OBS API right now.

So far there has only been one API version, which has been carefully extended.

Generally speaking we try to avoid API changes. Though there are rare cases were we do them nonetheless. Here is a list of different types of API changes and how we handled them.

Routes in the /public namespace are not considered part of the official API and can be changed in a more liberal way.

1. Adding new routes to the API

   Not a problem since there are no existing API consumers relying on this route.

2. Removing routes

   In a few cases we dropped existing routes. When we did this we deprecate them in the next OBS release and remove them in the second next one.

3. Adding new elements or attributes (as in XML elements) to existing API resources.

   This happens rarely and we try to avoid it, since it's easily affecting existing API consumers. In the few cases where we did this we:

   • Provided new releases for existing, supported OBS releases, to make older OBS versions compatible with the changed API.
   • Ensured that current osc versions (as in osc packages available for SLE11 SPx, SLE12 SPx, openSUSE releases, etc.) can handle these changes.

4. Changing error codes

   We don't change error codes. They should always stay the same. But adding additional error codes is possible.