New standard for OpenProject API

OpenProject offers a powerful API which allows other applications to access your OpenProject application for any kind of integration. However, we found that for some of our users the current OpenProject API is not as easily accessible. That is why our developer team worked on improving the documentation.

The API concept

The OpenProject team has implemented the OpenAPI 3 standard which can facilitate the work with our API. On top, they integrated the Swagger UI which means the developer can test the API directly in the OpenProject application. The Swagger UI visualizes and interacts with the API’s resources without having any of the implementation logic in place, making it easy to play around with the API without writing a line of code.

Working with OpenAPI

Since the API is defined in OpenAPI you can use various OpenAPI tools to help speed up integrating the OpenProject API.

If you want to create a work package in OpenProject via the API, you can create an API client in your language of choice using, for example, Swagger CodeGen with OpenProject’s OpenAPI spec.

The spec is available as both json and yaml and served by your OpenProject under /api/v3/spec.json (e.g. community.openproject.org/api/v3/spec.json) and /api/v3/spec.yml respectively.

Using Swagger UI

You can directly test the API on your running OpenProject installation by navigating to /api/docs (e.g. https://community.openproject.org/api/docs) and test the various endpoints which are listed there. A static version of the docs is available on our website. Both the interactive and the static version are generated based on the same OpenAPI spec.

For each endpoint the description is shown along with any expected parameters. There are example responses as well as examples for what the request body is expected to look like.

Moreover you can directly execute requests within the docs to try out the API. If you are logged in already you don’t need to provide credentials. If not you can provide credentials by clicking on the lock icon next to an endpoint. You can change the request body to your liking and click execute to test any API call. The resulting response will be shown below.

This allows users to test the API without having to write any code at all and makes it a lot easier to understand it.

Why is OpenProject using OpenAPI?

We love the OpenAPI Initiative’s (OAI) work promoting a vendor neutral description format. It works well with our understanding as a free and open source software that enables easy and effective collaboration on software development and distribution without any need for reverse engineering.