API changelog for epoch 0.x.x

This file describes the changes made to the API during the development. It is sorted in reverse chronological order.

For the most up to date API description please see the specification directly. This serves only for developers to find the changes better.

Unpublished

Version 0.1.3 - cookbook v0.11.5 - 2025-10-30

Deprecation of /api/version endpoint and adding OCS capability

The endpoint /api/version is deprecated. In favor of using it, the same information is provided as part of the capabilities of Nextcloud. These are available as /ocs/v2.php/cloud/capabilities. Please note that there are some minor modifications needed to use this end point.

• You need to provide a header OCS-APIRequest: true
• The cookbook version is no longer present. Use the API version instead or log in.
• As we are using OCS. This makes some modifications on your side necessary
  • All data is in a data key
  • The capabilities are not cookbook-filtered, so you have to look at the cookbook key

The old endpoint is just deprecated. I will remove it in some time.

Version 0.1.2 - cookbook v0.10.3 - 2023-12-04

Deprecation of recipe_id in recipe stubs

The current implementation has a minor inconsistenncy that for Recipe objects, there is a id as string and for RecipeStub objects, there is a recipe_id as int. This is inconsistent.

As the string based indexing is preferred for future enhancements, the legacy recipe_id in RecipeStub is deprecated. Instead, a new entry id is added as sting value.

For the meantime, the index will be present in both properties until the next release will drop the old behavior.

Version 0.1.1 - cookbook v0.10.2 - 2023-03-24

Remove deprecated endpoints

The duplicated (deprecated) endpoints in v0.9.15 are removed. Only the endpoints under /webapp/ or /api/v1/ are working in the future. See also the section.

Fix OpenAPI format specification

There were some minor flaws and typos in the spec file. These flaws caused some code generation tools to fail or produce incomplete results.

The fixture of these issues should not be critical as these are mainly cosmetic and will not change the actual transmitted data.

Removed some typos

Some typos in the API description was fixed. This does not change any behavior in the server but describes the actual transmitted data more precise.

Unless you use code generation, this will not affect you.

Add operation IDs

In accordance with #1421 the ids of all operations in the external API are defined. This should make it simpler to create clients using code generation techniques.

If the operaionId field is not used, this should not change anything. Otherwise, the names of the methods might need updating.

Version 0.1.0 - cookbook v0.9.15 - 2022-09-08

See API specification

Split and rename API endpoints

There is a security issue with the previous API version 0.4.0, see this description. As a result, all endpoints need a renaming to be able to fix the security issue.

All publicly available endpoints are now located under the /api/v1 prefix. Endpoints were prefixed with either /api/v1 (if not already prefixed by /api) or the /api was replaced by /api/v1 in all URLs.

The behavior of the endpoints was not changed.

Version 0.0.4 - cookbook v0.9.13 - 2022-07-02

See API specification

Remove old API endpoints

The endpoints GET on /recipes/create and PUT on /recipes/{id}/edit are deprecated and no longer working. These are just removed to clean up the api endpoint list.

Version 0.0.3 - cookbook v0.9.12 - 2022-05-12

See API specification

Allow the client to specify the accepted image types

The client was not able to specify the compatible image types. The endpoint /recipes/{id}/image just served whatever format was available, be it JPG or SVG.

The endpoint now respects the Accept request header and does not send a SVG if only JPGs are requested explicitly. If no matching file type was found, a status of 406 is returned.

This affects the following API endpoints:

• GET in /recipes/{id}/image can return 406

Related issues: #954

Prevent adding of recipes with no name

We are currently storing the recipes in a folder according to the recipe name. If no name was provided, this breaks our storage backend. Until now, a 500 error was returned. This was changed to be 422 with some useful error handling.

This affects the following API endpoints:

• POST on /api/recipes can return 422
• PUT on /api/recipes/{id} can return 422

Related issues: #923

Version 0.0.2

See API specification

This version was the first version to be well documented. It was called 0.0.2 as 0.0.1 would be the (undocumented) initial API structure. So, please consider this the fist stable API version.

Additionally, some API endpoints were deprecated/removed. They were not related to a REST-based APi but the ancient multi-page site approach. These endpoints were non-functional anyways.