Naming for a REST webservice

Question

I have a rest webservice with an endpoint www.foobar.com/service.svc/MAC (migration authorisation code). Posting and getting to that adds and gets one MAC respectively. I now need to impliment a new enpoint for all MACs. What would that be? www.foobar.com/service.svc/MAC/All seems wrong. What would be correct and why?

Answer 1

Here's what REST usually looks like

GET www.example.com/service.svc/MAC - gets a list of all the MACs
GET www.example.com/service.svc/MAC?{property}={value} - search MACs by specified properties
POST www.example.com/service.svc/MAC - creates a new MAC
GET www.example.com/service.svc/MAC/{id} - gets the MAC with the specified id
PUT www.example.com/service.svc/MAC/{id} - updates the MAC with the specified id
DELETE www.example.com/service.svc/MAC/{id} - deletes the MAC with the specified id

There are a few less used operations as well: PUT /MAC would replace the entire collection of MACs, DELETE /MAC would delete everything, and POST /MAC/{id} would create subitems in the MAC, but it looks like you won't be needing those.

Answer 2

The following offers a suggested set of URI naming guidelines for REST services that have worked for me in practice.

The book RESTful Web Services RESTful Web Services defines three basic rules for url design which act as a great starting point:

• Use path variables to encode hierarchy: /parent/child 
• Put punctuation characters in path variables to avoid implying hierarchy where none exists: /parent/child1;child2 
• Use query variables to imply inputs into an algorithm, for example: /search?q=jellyfish&start=20 

 Other guidelines include:

• URIs should ideally not change over time. 
• Services offering a uniquely identifiable resource via a key should use basic rest notation (e.g. /accounts/(accountid) ) 
• Services offering optional search/filtering capabilities should use query parameter ? key1 = value & key2 = value notation (e.g. /instruments?ticker=FT) 
• Services expecting mandatory arguments over GET should have them as path variables (e.g. /accounthistory/(fromdate)/(todate)
• All rest service names should use strict low case names (e.g. /client) 
• The elements of the URI should map to business entities and the mapping should be consistent. For example a business entity named contentpartner should be consistently referred to as contentpartner(s) in all URIs (rather than a mix of partner, cp etc).  A good starting point would be the name of the domain object. 
• Parameters that do not define a resource but qualify it (e.g. locale which feeds into the translations of the data) should not form part of the normal URI space.  Consider using headers or optional query parameters for these
• Use nouns, not verbs.  The power of REST comes through the fact there is a limited verb set (operations) combined with a large set of nouns (or resources). Consequently the manner in which these nouns are constructed is of great importance. 
• Avoid suffixes.  When designingURIs it is paramount that they refer to the thing that is being operated upon rather than the operation being performed. Secondly, the client is interested in the resource - not the implementation of the server software that powers the service. It is desirable to avoid suffixes such as .jsp or .aspx.
• Use Accepts Header for content negotiation
• Keep It Intuitive. URIs should be human readable or guessable. The easiest way to do this is to construct a URI hierarchy, grouping related items together. Such patterns of category and subcategory are very easy to understand.

Answer 3

RESTful way for listing all MACs is:

GET www.foobar.com/service.svc/MAC

Why? Well, because it's a convention and people expect REST service to behave that way.

If you want to read more on that topic, check out how RESTful routing is done in Rails.

Answer 4

I posted a series of guidelines here: http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html

These are being used effectively, where I work.

UPDATE - I pasted the contents into another answer....

Robert