API Design - JSON or URL Parameters?

Question

I am just starting to learn how to design/write RESTful APIs. I have a general question:

Assume I have some sort of simple SQL database and I'm writing an API that allows to create a new record, view records, delete a record or update a record.

Assuming I want to delete a record, is it usually better to pass in the ID of the record in the URL, for example, /api/delete_record?id=10, or is it better to do something like:

/api/record and have it accept GET, POST, PATCH and DELETE, and the data is handled through the JSON body in the request.

I've written a small API using Flask in Python and what I have is just one URL: /record which accepts all the above HTTP methods. It looks at the method in the request and expects the request body in JSON accordingly. Is that considered good or bad practice?

Any suggestions would be greatly appreciated. Please note that I am still very new to all of this. I've worked with APIs before but I've never developed any. Thanks!

Facundo Olano · Accepted Answer · 2012-11-13 17:27:46Z

3

The proper RESTful way of deleting a resource is to send a DELETE request, and put the scoping information in the URI (not the body), like /api/records?id=10 or /api/records/10. The method information should be in the HTTP method, not the URI.

I suggest you read "RESTful web services" to learn the best practices on API design.

answered Nov 13, 2012 at 17:27

Facundo Olano

2,6193 gold badges31 silver badges34 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

darksky Over a year ago

What about update (HTTP PATCH)? Would you pass in the ID in the URI and the JSON request body with the contents? Or all of the content as URI parameters?

Facundo Olano Over a year ago

You probably should use PUT for updates (apparently PATCH is ok for partial updates, I'm not sure on that, but for the general case is PUT). As a rule of thumb, you put the method in the, well, HTTP Method, all the scoping information (to identify which resource you want to interact with) in the URI, and the data in the body. So for the update you would put the contents on the json body.

Collectives™ on Stack Overflow

API Design - JSON or URL Parameters?

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related