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, 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


/image - get an image using attachmentlink

/download - download a file using attachmentlink

Example jQuery:

cache: false,
beforeSend: function (oRequest)
oRequest.setRequestHeader("X-HTTP-myds-rest-level", "1");


More information:


  • 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.


  • 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.