What is the best practice to write custom RESTful API endpoints?

Suppose we have an entity named Comments. And there's regular CRUD for interacting with API requests through below URLs:

GET : /:postId/comments
POST /:postId/comments
GET /:postId/comments/:commentId
PUT /:postId/comments/:commentId
DELETE /:postId/comments/:commentId

My problem begins when we need to add a new endpoint to either reject or accept by some administrator working with the application.

Here are some available scenarios to achieve this functionality:

Define a new route with a PUT method and /moderate URL
Define two new routes with PUT methods and /accept or /reject URL
Define a whole new resource to moderate the comments
Send some extra info through the existing /:postId/comments/:commentId URL to tell the controller we're moderating

What's the best practice to develop this kind of endpoints?

It does not matter as long as your team understands. Use tools like Swagger to document the API. Of your 4 options, I will avoid 3, technically, it doesn't matter.

We did an entire (we feel most complete list) of articles and resources on best practices for API:

Apiguide.io

I don't know if there is a best practice, however, I would be pragmatic, because there are many good ways to solve the problem. For example:

add a new endpoint to either reject or accept

I don't know the data structures, so let me assume that whatever data structures you use include the comment plus any metadata. Let's say, it looks like this:

interface Author { /* ... */ }

enum Status {
  PENDING,
  APPROVED,
  REJECTED,
}

interface Comment {
  author: Author
  content: string
  status: Status
}

So, what you may do is use a POST call to modify the resource and update the status.

POST /:postId/comments/:commentId

Content-Length: 17
Content-Type: application/json
Cookie: user-token: xxxxxxxyxxxxxxx000
X-XSRF-TOKEN: abc123

{
  "status": 1
}

Anyone who is authorized to modify can now change the status. You may, though, add some extra logic to the field, so it can only be set by users with special privileges.

user := get_user_from_token(user-token)
if (is_admin(user))
  update_status(body.status)
  send_to_client(200)
else
  send_to_client(403)

Wouldn't it a bad practice to put your foot outside of REST principles and define a route that doesn't fit inside its rules?

I mean having a URL with a POST method that updates a state is not what REST recommend.

It's called PUT or PATCH but technically you can only do a GET or POST accordingly to the HTTP protocol. So what you do is a POST and somehow detect it as PUT, for example by adding a _method=put

Ehsan Fazeli POST is a valid HTTP method, which should be used in order to update a resource (see mdn). It is also a valid RESTful method to work with resources:

Because HTTP, the standard protocol behind the Web, also transfers documents and hypertext links, simple HTTP APIs are sometimes colloquially referred to as RESTful APIs, RESTful services, or simply REST services, although they don't necessarily adhere to all REST constraints. Beginners can assume a REST API means an HTTP service that can be called using standard web libraries and tools.

(mdn)

tl;dr: Whenever you can create, get, modify or delete a resource using PUT, GET, POST and DELETE in a stateless way, it might already be a RESTful API.

I quote mdn a lot here, because it is an official web documentation based on the actual W3C RFCs and maintained by big names, like Mozilla, Google, W3C, Samsung and Microsoft (source, mdn board members).

Thread

What is the best practice to write custom RESTful API endpoints?

Responses(3)

Recent threads

Search Hashnode

What is the best practice to write custom RESTful API endpoints?

Responses(3)

Recent threads