 <p>I think that this link could give you some hints about the design of RESTful services / Web API: <a href="https://templth.wordpress.com/2014/12/15/designing-a-web-api/" rel="nofollow">https://templth.wordpress.com/2014/12/15/designing-a-web-api/</a>.</p> <p>It's clear that not all Web services that claim to be RESTful are really RESTful ;-)</p> <p>To be short, RESTful services should leverage HTTP methods for what they are designed for:</p> <ul> <li>method <code>GET</code>: return the state of a resource</li> <li>method <code>POST</code>: execute an action (creation of an element in a resource list, ...)</li> <li>method <code>PUT</code>: update the complete state of a resource</li> <li>method <code>PATCH</code>: update partially the state of a resource</li> <li>method <code>DELETE</code>: delete a resource</li> </ul> <p>You need to be also to be aware that they can apply at different levels, so methods won't do the same things:</p> <ul> <li>a list resource (for example, path <code>/elements</code>)</li> <li>an element resource (for example, path <code>/elements/{elementid}</code>)</li> <li>a field of an element resource (for example, path <code>elements/{elementid}/fieldname</code>). This is convenient to manage field values with multiple cardinality. You don't have to send the complete value of the fields (whole list) but add / remove elements from it.</li> </ul> <p>Another important thing is to leverage HTTP headers. For example, the header <code>Accept</code> for content negotiation...</p> <p>I find the Web API of Github well designed and its documentation is also great. You could browse it to make you an idea. See its documentation here: <a href="https://developer.github.com/v3/" rel="nofollow">https://developer.github.com/v3/</a>.</p> <p>Hope it helps you, Thierry</p>