REST - Introduction

1. REST - Introduction • Based on material from InfoQ.com (Stefan Tilkov) • And slides from MindTouch.com (Steve Bjorg)

2. Key REST principles • REST is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used • The principles: • Give every “thing” an ID • Link things together • Use standard methods • Resources with multiple representations • Communicate statelessly

3. Give every “thing” an ID • Everything that should be identifiable should obviously get an ID • On the Web, there is a unified concept for IDs: The URI. • URIs make up a global namespace, and using URIs to identify your key resources means they get a unique, global ID. • It is not a pre-requisite in REST to construct human readable URIs, but it makes it easier to use. • Use URIs to identify everything that merits being identifiable, specifically, all of the “high-level” resources that your application provides, whether they represent individual items, collections of items, virtual and physical objects, or computation results.

4. Give every “thing” an ID • What is the difference betweens the URIs in the first box compared to the second box? • http://example.com/customers/1234http://example.com/orders/2007/10/776654http://example.com/products/4554http://example.com/processes/salary-increase-234 • http://example.com/orders/2007/11http://example.com/products?color=green

5. Link things together • “Hypermedia as the engine of application state”, HATEOAS • Hypermedia: the idea of links – as in HTML <orderself='http://example.com/customers/1234' > <amount>23</amount> <productref='http://example.com/products/4554' /> <customerref='http://example.com/customers/1234' /> </order> • An application can get information about product and customer by following the links • Use links to refer to identifiable things (resources) wherever possible.

6. Use standard methods • The standard methods (verbs) of HTTP are: • GET (request a resource) • POST (usually create new resource) • PUT (update or create ressource) • DELETE (delete ressource) • HEAD and OPTIONS • Using HTTP ensures that the opponent knows what you mean. • Also the HTTP methods, except POST, are idempotent, so you may call a method, e.g. GET, again if you don’t receive a response • RESTful services must obey the restrictions of HTTP • But is that really a problem? See next slide

7. Example • Traditional service interfaces: • The services and operations are connected to a specific resource • Therefore the client must have specific knowledge of the interface/ application protocol

8. Example (procurement)RESTful • In a RESTful HTTP approach, you would have to get by with the generic interface that makes up the HTTP application protocol. • The specific operations of the service are mapped to the standard HTTP methods • E.g. A GET on a URI that identifies a customer is just as meaningful as a getCustomerDetails operation

9. Compare traditional services and RESTful services • The triangle: Pick any two • In traditional services you might have many operations, many data types but few instances (Services, remote objects, endpoints etc.) • In RESTful services you have a limited number operations (4), many data types and many instances (could be any thing on the web, i.e. http servers, gateways, providers like Google, Yahoo, Live, etc.) • Recap: For clients to be able to interact with your resources, they should implement the default application protocol (HTTP) correctly, i.e. make use of the standard methods GET, PUT, POST, DELETE.

10. Resources with multiple representations • How does a client know how to deal with the data it retrieves, e.g. as a result of a GET or POST request? • The approach taken by HTTP, is to allow for a separation of concerns between handling the data and invoking operations. • In other words, a client that knows how to handle a particular data format can interact with all resources that can provide a representation in this format. How does this differ from OOP?

11. Resources with multiple representations • Using HTTP content negotiation, a client can ask for a representation in a particular format: GET /customers/1234 HTTP/1.1 Host: example.com Accept: application/vnd.mycompany.customer+xml GET /customers/1234 HTTP/1.1 Host: example.com Accept: text/x-vcard You can also do it explicit in the URI, e.g. /customers/1234?vcard or • /customers/1234/vcard

12. Resources with multiple representations • Ideally, the representations of a resource should be in standard formats • If a client “knows” both the HTTP application protocol and a set of data formats, it can interact with any RESTful HTTP application in the world in a very meaningful way. • Unfortunately, we don’t have standard formats for everything, but you can create some for your own ecosystem. • Of course all of this does not only apply to the data sent from the server to the client, but also for the reverse direction • A server that can consume data in specific formats does not care about the particular type of client, provided it follows the application protocol.

13. Resources with multiple representations • If you provide both xml and html, you can turn your application’s Web UI into its Web API • API design is often driven by the idea that everything that can be done via the UI should also be doable via the API. GET /customers/1234 HTTP/1.1 Host: example.com Accept: application/vnd.mycompany.customer+xml GET /customers/1234 HTTP/1.1 Host: example.com Accept: text/html

14. Communicate statelessly • Most applications are not stateless • But the state should be kept in the client or in an resource • It means that the server should not maintain state for each client • One reason is that it makes the client independent of changes on the server side, and even makes it possible to use another server if the first one crashes during a transaction. • Another reason is scalability. It affect the servers performance if it must keep client state for a huge number of clients. • Therefore it not RESTful to use the session object

15. REST by Example Some slides from from MindTouch.com

16. Problem Statement Customer wants to update his order with ACME Enterprises

17. REST Example /customers/coyote GET Get the customer <customer> <name>Wile E. Coyote</name> <portrait>http://coyote.com/my_portrait.png</portrait> <orders>http://acme.com/customers/coyote/orders</orders> </customer>

18. REST Example /customers/coyote /customers/coyote/orders Get a list of customer’s orders GET GET <orders> <customer>http://acme.com/customers/coyote</customer> <next>http://acme.com/customers/coyote/orders?before=11</next> <order id="20"> <uri>http://acme.com/orders/1234</uri> <status>open</status> </order> ... </orders>

19. REST Example /customers/coyote /customers/coyote/orders /orders/1234 GET Get a specified order GET GET <order> <customer>http://acme.com/customers/coyote</customer> <status>open</status> <item quantity="1">ACME Rocket</item> </order>

20. REST Example /customers/coyote /customers/coyote/orders /orders/1234 GET Change the specified order GET GET PUT <order> <customer>http://acme.com/customers/coyote</customer> <status>open</status> <item quantity="4">ACME Rocket</item> </order>

21. REST Example /customers/coyote /customers/coyote/orders /orders/1234 GET GET GET PUT