Clear API specification, optimally machine-readable like OpenAPI

Feature requests
1

Hello zammad team,
I currently try implementing our application into zammad and ran into a huge workload regarding your API.

I’ll try and answer your Feature request questions:

1) What is your original issue/pain point you want to solve?

Zammad has a REST API that can do a lot from what I’ve seen. However, for a product of this scale and the target of being easily integratable, this API is IMHO not great. Even tho it’s versioned, the versioning doesn’t seem to be stable as seen here and the documentation lacks information about types. Some API endpoints are not explicitely documented like conditional search of tickets.

2) Which are one or two concrete situations where this problem hurts the most?

Please try and follow this scenario:

There’s only a couple official API clients. If you’d want to start integrating Zammad into a JS/TS project, you’d need to rely on a third party api-client or build one yourself because there is no official one for that. You find one here only to find out after some hours of testing that its implementation of Bearer and Token auth is completely broken and it lacks advanced search-endpoints. So you start building one yourself but for a complete client you need all the input/output types. The output types shown in the docs are full of empty arrays and null values of unknown type so you need a lot of try-and-error setting values on your zammad-instance just to find out the correct types. You got your API client working with a humongous amount of manual typing and after a while, you update your zammad. Your API client is now out of sync with the API schema, because under the /v1 endpoint, there are changes that nobody expected as it’s a versioned API. All your integrations are broken and you have to manually change everything in your client and your application to address this.

3) Why is it not solvable with the Zammad standard?

There is neither an official API client, nor a stable API, nor an OpenAPI definition to generate a client.

4) What is your expectation/what do you want to achieve?

Provide a machine-readable definition (OpenAPI) of the API so API-clients can be generated within seconds. Keep versions of the API (/v1) stable and only add functionality, don’t change it. Provide swagger UI for additional full documentation of types.

3 Likes
2

Thanks for this feature request. For sure, we have in mind to improve the current situation, like already mentioned in the linked thread, but we also have some kind of limited resources and need to find a good balance.

Please keep in mind that the API has not really changed much in the last releases, especially the main usage related to tickets and other important entities.
Normally, there is also always a depreciation announcement or fallback until it’s really removed (the situation in the linked thread was a little bit special, and we avoid such situations).

2 Likes
3

May I ask, how the API documentation is currently generated? Is this already an automatic process and is there some sort of machine-readable source from which it is created? In that case, it may be possible to also create an OpenAPI definition file.

4

Currently, the API documentation is handwritten and curated by humans to address the most common use cases. This approach provides maximum flexibility with regard to endpoints that are primarily used by the front end.

As you can see in the linked repository, the main contributor is a technical writer employed by Zammad GmbH. However, as with other Zammad products, there is a way to contribute to the documentation.

Automatic API documentation is not currently planned, but this may be considered in the future. In addition to REST, GraphQL is already partially available, and MCP may be added in the future as well.

1 Like
5

Thank you for the insights @YetAnotherGerrit and @dominikklein!