6

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?

Improve this question

4 Answers 4

Reset to default
15

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.

Improve this answer
3
  • 2
    Also notice that as a response to "POST www.example.com/service.svc/MAC" the server should return 201 plus Location header for the newly created resource, if successful.
    – Mikko Rantalainen
    May 7, 2012 at 12:36
  • @configurator isn't post supposed to be update and put supposed to create the MAC ?
    – vikkyhacks
    May 10, 2014 at 14:11
  • @vikkyhacks that's what I used to think but I eventually found out I had been mistaken.
    – configurator
    May 10, 2014 at 17:50
5

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.




Improve this answer
1

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.

Improve this answer
0
0

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

Improve this answer
2
  • 1
    Hello @Robert! Answers that are link-only aren't very good, since if the link rots, your answer won't mean anything. Maybe you could add the general guidelines you specify in your blog here?
    – Florian Margaine
    Oct 5, 2012 at 9:35
  • You could have edited this question instead. Would be good to delete this one now.
    – deadly
    Oct 10, 2012 at 8:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.