Development Documentation for api development

As a new comer to foreman I am having a difficult time completing simple tasks, which in a normal rails project is a breeze.

We need a detailed documentation on the api and how to implement new api endpoints including nested api endpoints and everything surrounding them including, but not limited to pagination, filters, permissions, etc etc.


Your best bet would to be look at an existing API controller either in Foreman core or a plugin, depending what you’re doing. If you have a specific question about how to do something we can help, but I can’t point you at any extensive documentation other than for plugins - Plugins - Foreman, which might answer some of your questions.

The API itself is documented using Apipie, and you can find the documentation for usage the API as a client at /apidoc on your Foreman server.

I should also mention, there are things like the developer handbook and contribution guide, but I don’t think they’re providing the implementation details you’re looking for.

Sorry for the late reply. I checked out the developer handbook and contribution guide, but it didn’t help me very much.

Looking at other plugins for examples of how it is done is not always helpful since there are still unanswered questions left when things get complicated or things start going wrong, and its not clear how to do it properly.

Its not about documentation of implemented api’s but rather how exactly to implement a new api within a plugin. There is a fair amount of custom code (in core) that has been implemented to make adding api endpoints simpler, but there is no explanation about what is exactly possible, what methods are available and what they are used for, etc etc. This is also very important as otherwise it is very easy to implement new api endpoints in different ways to what is actually intended by foreman core.

I think everyone is for more documentation around API development, but it’s just up to someone to do it. A good start would be to write down your questions and we can discuss them here and help you out. Then this could turn into actual written documentation for writing the API in plugins.

Ok cool, I will gather my questions and post them here.