RESTful API design best practices [closed]

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 7 years ago.

Improve this question

I am current writing an API layer for my project, and a开发者_StackOverflowm struggling with trying to figure out a good design approach for the following scenario:

1. All users have a list of books
2. Each list can be accessed via an ID
3. Users can add and delete books at will

Currently, I'm not sure which the best approach would be:

1) PUT - /api/list/{listID}/{bookID} - Add book to specified list
   DELETE - /api/list/{listID}/{bookID} - Remove book from specified list
2) PUT - /api/list/{listID} - Send XML data to server that contains bookID and action
   <list_payload>
       <action>{delete|add}</action>
       <bookID>{bookID}</bookID>
   </list_payload>

Any insight would be appreciated.

---

I think like this

1)POST - /api/lists/{listID}/books - Add book to specified list
2)PUT - /api/lists/{listID}/books/{bookID} - Edit book from a specified list
3)DELETE - /api/lists/{listID}/books/{bookID} - delete

for List

POST - /api/lists Add list
PUT - /api/lists/{listID} Edit list
DELETE /api/lists/{listID} Delete list

---

There is no constraints in REST because is more a way to resolve things via HTTP and not a hard web services protocol with a strong standard like SOAP.

Said that, both options could be valid but for the sake of simplicity I've think you must to go by your first option.

---

I think this a very good and clear guide to understand how to design a proper REST service. It is not only covers this question but gives more clue for to the design process.

You can watch: https://www.youtube.com/watch?v=hdSrT4yjS1g Or you can quick look: http://www.slideshare.net/stormpath/rest-jsonapis

---

I would interpret the first example as you are updating the book that exists within the list. Meaning, the book has set data by itself, but within the list it has more attributes which you can then update via the {listID}/books/{bookID} url.

If you are wanting to update the contents of the list (i.e. add or remove books) then calling PUT on the lists/{listID} url makes the most sense to me.

-Dan

---

As @MartinRevert indicated, there is really no constraints on REST API design other than ones you put in yourself.

For myself, I would suggest to focus on testability and UI developer simplicity rather than leveraging all the capabilities of the HTTP protocol. In the end they're you're clients and if their JavaScript framework does not follow all the HTTP resource conventions (Angular didn't for the 201 Created redirect in an earlier version)

GET is for retrieval of data. Primarily because it can be cached. This would return data of the appropriate content type.

POST is will modify data or accept complex search queries. In my contract this will always return a JSON object.

By keeping things to be just POST, you can create a simple form without having to do the XHR stuff to do some functional testing.

I wrote a more in-depth answer here http://www.trajano.net/2014/07/rest-api-contract/

---

Here's a link to an experimental JSon service with a source code download link for both web and Android: developersfound.com/RESTExperiment/

I've been doing a lot of experimental code in my spare time with REST. I've used and experimented with quite a lot of frameworks lately and I've gone the full circle and realized that simple HTTP JSon is the most effective. Most people say that statelessness is the advantage of REST but HTTP is stateless also. HTTP has the added advantage of having state if you need it; either connection state or session state. It is also more secure. However if you do insist on going down the REST route try to find a framework with a routing engine that doesn't use custom routes; that depend on regular expressions as this puts a big burden on the servers. Non regular expression routing puts a bit of a restriction on the way you design and develop your service, but it's worth it if you value fast servers with minimal bottlenecks. Another great way to minimize bottlenecks is to use stored procedures instead of pass-through queries. For those of you who don't know what a pass-through query is. It's just the opposite of using stored procedures, when the developer dynamically generates an SQL string at the server and passes it to the database. Stored procedures get rid of bottlenecks because pass-through queries cause the server to dynamically generate sql every time the server takes a hit. With stored procedures you only need pass the parameters from the request directly to the database. Also stored procedures are compiled meaning even the database does not have to generate the SQL dynamically. Pass-through queries became legacy when the SQL 92 standard came out in 1992. The link I have above is actually experimental code but you will find the blog very insightful.