I have a portfolio where I display my work (mostly backend API stuff with minimal UI to interact with) and am currently documenting the APIs. What I have is a page per project along with the documentation that belongs to it. In my APIs, I use a "base" endpoint named after the resource it works with (/todos, /posts,…). GET /todos would return a list of every todos from the DB, pretty standard stuff. I also use a "base" /me endpoint to be able to return every kind of resource of the current logged in user (that can be posts, todos,… ex: GET /me/todos would return every todos of the current user).

Because I have a page per project / documentation, should I list and document every /me endpoints in a separate page (for example, in my "Profile" page), or should I put them in their respective projects page ? Ex : In my "Todos" project page, I would document every /todos endpoint but also GET /me/todos and so on for every project.

I know this might sound like a stupid question, but it bugs me a little to mix the "base" endpoint of a project (ex: /todos) with this GET /me/todos endpoint (because then the /todos endpoint doesn't seem to be the "base" one anymore). But at the same time, I feel like having this GET /me/todos documented in the "Todos" project page would facilitate navigating and reading the docs.

Could someone point me in the right direction please ? Thank you very much

CodePudding user response：

If you develop a REST API, there is the uniform interface constraint, which includes the HATEOAS constraint, which says, that the API must serve hyperlinks and the client must rely on hyperlink metadata instead of URI structure. Something like ReadMyTodos instead of GET /me/todos. Worst case solution is adding a map like {"ReadMyTodos": ["GET", "/me/todos"]} to translate for the clients, but you won't get the same experience, because the client won't know what allowed on which page, so you need a map for that too {"/me": ["ReadMyTodos", "ReadMyPosts"]}. And this works only if every user has the same role in your API and every resource supports the same operation, the supported operation does not depend on the resource state, which is unlikely. Normally your API should not give error messages, because you want to update a post that was closed by an admin. This is because the hyperlink for updating the post must not show up on the hyperlink list at all. If you don't return hyperlinks, then the clients would try if the operation is available and they will rely on trial and error for not reason.

If you don't want to use the upper approach and so we are not talking about a REST API, then the GET /todos and the GET /me/todos return a different list for the same user, then you must document them separately. This does not necessarily mean that they need to be on separate documentation pages. You can use sections/divisions to separate them on a single page if they are interrelated. E.g. you can have links related to Todos and you document them on a single page and usually have a list of links on the top of the page and local anchors with hashtags for sections something like /docs/Todo#ReadMyTodos.