Finalize API for version 1.0

[seyfeb]

A stable version of the public API should be defined for the 1.0.0 version of the app.

As far as I can see, we currently have the following endpoints which should be brought into a clean, consistent state if necessary to form a stable basis for 1.0.

All endpoints are relative to the /app/cookbook prefix.

End-user interface

• HTML index page (/ GET)

API

• getApiVersion (/api/version GET)

Recipes

• get all recipes (/api/recipes GET)
• get single recipe (/api/recipes/{id} GET)
• create new recipe (/api/recipes POST)
• Update recipe (/api/recipes/{id} PUT)
• Remove a recipe (/api/recipes/{id} DELETE)
• get all recipes by category (/api/category/{category} GET)
• get all recipes by tags (/api/tags/{keywords} GET)
• search (/api/search/{query} GET)
• import (/import POST)
• Get the image of a recipe (/recipe/{id}/image?size={size} GET)

Categories

• get all categories (/categories GET)
• update name (/api/category/{category} PUT)

Keywords

• get all keywords (/keywords GET)

Configuration

• read (/config GET)
• update (/config POST)
• reindexDatabase (/reindex POST)

Are we using any of those routes?

['name' => 'main#home', 'url' => '/home', 'verb' => 'GET'],
['name' => 'main#error', 'url' => '/error', 'verb' => 'GET'],
['name' => 'main#create', 'url' => '/recipes/create', 'verb' => 'GET'],
['name' => 'main#new', 'url' => '/recipes/create', 'verb' => 'POST'],
['name' => 'main#edit', 'url' => '/recipes/{id}/edit', 'verb' => 'GET', 'requirements' => ['id' => '\d+']],
['name' => 'main#update', 'url' => '/recipes/{id}/edit', 'verb' => 'PUT', 'requirements' => ['id' => '\d+']],
['name' => 'main#recipe', 'url' => '/recipes/{id}', 'verb' => 'GET', 'requirements' => ['id' => '\d+']],

This issue is supposed to be a discussion of the v1 API.

• Which endpoints can be removed?
• Is the structure clear and consistent?
• What should be changed?

[christianlupus]

I will add @Teifun2 as this is highly interesting for him.

[christianlupus]

I suggest moving all endpoints that return JSON data (which is most of them) should be under the prefix /api. That is relevant for /config and /import, possibly also others. Further, I suggest moving all API endpoints into a versioned endpoint. So instead of a prefix /api once we are fixed we should use /api/v1 and not change that anymore once published.

Regarding the potentially obsolete endpoints, we have to carefully check these. After that, we can drop the controller functions if no longer in use.

BTW I am not sure if you put all routes there...

What do you think?

[seyfeb]

I agree with your proposal in general. However if any non-API breaking changes are made (adding additional endpoints) these may still be added to /api/v1, imho.

@christianlupus If I might have missed a route - feel free to add it! ;)

[christianlupus]

Yes, you are right. Extending endpoints without breaking changes in a fixed version is ok. I am going to have a look at the present routes and update accordingly.

I updated your entry to reflect my findings. Additionally, I opened a PR #580 to get the deprecation notices into the code. Some of these might even no longer work as files are missing.

I am intending to write an API specification that allows to easier define the exact outline and simpler development.