Special Topics – Persistent Worlds

REST

REST

REST is an acronym standing for Representational State Transfer A software architecture style for building

scalable web services Typically, but not always, communicate

over the Hypertext Transfer Protocol with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) web browsers use to retrieve web pages

REST (cont.)

Performance - component interactions can be the dominant factor in user-perceived performance and network efficiency

Scalability to support large numbers of components and interactions among components

Simplicity of interfaces Modifiability of components to meet changing needs

(even while the application is running) Visibility of communication between components by

service agents Portability of components by moving program code

with the data Reliability is the resistance to failure at the system

level in the presence of failures within components, connectors, or data

REST (cont.)

REST constraints: Client–server Stateless Cacheable Layered system Uniform interface

REST (cont.)

Web service APIs that adhere to the REST architectural constraints are called RESTful APIs.

Aspects of HTTP based RESTful APIs: Base URI, such as http://example.com/resources/ An Internet media type for the data. ▪ This is often JSON but can be any other valid Internet

media type (e.g. XML, Atom, microformats, images, etc.) Standard HTTP methods (e.g., GET, PUT, POST, or

DELETE) Hypertext links to reference state Hypertext links to reference related resources

REST Request

http://www.acme.com/phonebook/UserDetails/12345

http://www.acme.com/phonebook/UserDetails?firstName=John&lastName=Doe

GET requests should be for read-only queries Creation, updating, and deleting data, use POST

requests

REST Examples

The Google Glass API, known as "Mirror API", is a pure REST API

Twitter has a REST API https://dev.twitter.com/docs/api

Flickr http://www.flickr.com/services/api/

Amazon.com offer several REST services, e.g., for their S3 storage solution,

Tesla Model S uses an (undocumented) REST API between the car systems and its Android/iOS apps.

REST architecture

Resources, which are identified by logical URLs. Both state and functionality are represented using resources. The logical URLs imply that the resources are

universally addressable by other parts of the system.

Resources are the key element of a true RESTful design▪ You do not issue a "getProductName" and then a

"getProductPrice“▪ You view the product data as a resource -- and this resource

should contain all the required information (or links to it).

REST architecture (cont.) There is no connection state; interaction is

stateless (although the servers and resources can of course be stateful). Each new request should carry all the information

required to complete it, and must not rely on previous interactions with the same client.

Resources should be cachable whenever possible (with an expiration date/time). The protocol must allow the server to explicitly

specify which resources may be cached, and for how long.▪ Since HTTP is universally used as the REST protocol, the

HTTP cache-control headers are used for this purpose.

REST Design Guidelines

Do not use "physical" URLs. A physical URL points at something physical -- e.g., an XML file:

▪ "http://www.acme.com/inventory/product003.xml". A logical URL does not imply a physical file:

▪ "http://www.acme.com/inventory/product/003". Queries should not return an overload of data.

If needed, provide a paging mechanism. ▪ For example, a "product list" GET request should return the first n products (e.g., the first 10), with

next/prev links. Even though the REST response can be anything, make sure it's well documented,

and do not change the output format lightly (since it will break existing clients). Rather than letting clients construct URLs for additional actions, include the actual

URLs with REST responses. Bad design: A "product list" request could return an ID per product, and the specification

says that you should use http://www.acme.com/product/PRODUCT_ID to get additional details.

Rather, the response should include the actual URL with each item: ▪ http://www.acme.com/product/001263

Yes, this means that the output is larger. But it also means that you can easily direct clients to new URLs as needed, without requiring a change in client code.

GET access requests should never cause a state change. Anything that changes the server state should be a POST request (or other HTTP verbs,

such as DELETE).

Using REST

PHP http://

rest.elkstein.org/2008/02/using-rest-in-php.html

JavaScript http://rest.elkstein.org/2008/02/using-res

t-in-javascript.html C#

http://rest.elkstein.org/2008/02/using-rest-in-c-sharp.html

Resources

Slim http://www.slimframework.com/

Using The Slim PHP Framework for Developing REST APIs http://codingthis.com/databases/using-the-slim-php-framew

ork-for-developing-rest-apis/#comment-24213

RESTful services with jQuery, PHP and the Slim Framework http://coenraets.org/blog/2011/12/restful-services-with-jquer

y-php-and-the-slim-framework/

Writing a RESTful Web Service with Slim http://www.sitepoint.com/writing-a-restful-web-service-with-

slim/

Resources (cont.)

Video REST+JSON API Design - Best Practices for

Developers▪ https://www.youtube.com/watch?v=hdSrT4yjS1g

How to create REST API for Android app using PHP, Slim and MySQL http://www.androidhive.info/2014/01/how-t

o-create-rest-api-for-android-app-using-php-slim-and-mysql-day-12-2/

http://www.androidhive.info/2014/01/how-to-create-rest-api-for-android-app-using-php-slim-and-mysql-day-23/

Resources (cont.)

List of 40 tutorials on how to create an API http://blog.mashape.com/list-of-40-tutori

als-on-how-to-create-an-api/

Building Web Services the REST Way http://www.xfront.com/REST-Web-Service

s.html