GETTING STARTED
REST

Representational state transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web.

"REST has emerged over the past few years as a predominant Web service design model. REST has increasingly displaced other design models such as SOAP and WSDL due to its simpler style.

The term representational state transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation. Fielding is one of the principal authors of the Hypertext Transfer Protocol (HTTP) specification versions 1.0 and 1.1." - wikipedia

mydigitalstructure & REST Taking a step back, mydigitalstructure can be used in both a RPC and REST architecture.   A lot of the mydigitalstructure documention and examples are based on RPC principles. REST sits above this and using hypermedia and some payload standards creates the "story" of the represented information via hyperlinks/links.  mydigitalstructure has an single entry point that allows it to be consumed into a RESTful enviroment. The REST client (eg web-browser, iPhone...) sends a request over HTTP/HTTPS to either: request information (eg list of contacts)   change the state of some information (eg change the phone number of a contact).  Based on the Richardson Maturity Model, mydigitalstructure.com is a Level 2 service - although we do allow a developer to use a GET to change state if they choose. We currently have a project underway to increase the maturity level of the mydigitalstructure REST interface. You can use a hybrid rpc-rest methodology - eg getting not logged on response as a 401 http status.  To do this, either: Set X-HTTP-myds-rest-level equal to "1" in the request header Add &rest=1 to the data payload Example jQuery: $.ajaxSetup( { cache: false, beforeSend: function (oRequest) { oRequest.setRequestHeader("X-HTTP-myds-rest-level", "1"); } });

More information:

• REST
  wikipedia
   
• HATEOAS
  Hypermedia as the Engine of Application State
   
• REST Tutorial / Best Practice
  a must read!
  
  
• REST in Practice
  a great read
   
• Restful Webservices
  also a great read
   
• Explanation of Richardson Maturity Model by Martin Fowler
  thank you Martin
   
• HTTP Methods
  verbs: GET, POST, DELETE...
   
• HTTP Response Status Codes
  200, 201...
   
• HAL - Hypermedia Application Language
  a lean hypermedia type, application/hal+... 

MYDIGITALSTRUCTURE IMPLEMENTATION:

• POST to create
• PUT to update
• GET to search/retrieve
• DELETE to remove
• HEAD for object attributes (meta)
• HAL for linking & connectiveness
• Return format set by mediatype.
• Status codes used to augment OK/ER returns.

STATUS CODES:

• 200/OK - default
• 201/Created - When a new object item is added via POST.
• 202/Accepted - when an object item is updated via PUT.
• 406/Not Acceptable - when mandatory data is missing or a model rule has be violated.
• 401/Not Authorised - when undefined mydigitalstructure method or not rights.
• 304/Not Modified - if ER with PUT on existing object item.
• 404/Not found - if GET on existing object item and not found.