Development Lessons

of ReST APIs

Presented by Bil MowryIvy Street Technology LLC

Abstract

Restful application implementation encompasses a series design, communication and testing concerns for every developer. In Development Lessons of ReST APIs, we will walk through the steps and challenges of creating a ReST API: defining, designing, documenting, and testing.

Goal

The goal of this session is to share notes I have taken over several projects in thinking about, designing, implementing, testing and ReSTful services.

Focus not on implementation but rather on the output and strategies around design.

Questions! Always.

Major Points

1. What is a ReST API?2. Designing3. Documenting4. Testing5. UI Considerations6. Final Thoughts

1. What is a ReST API?

• Definition• What are ReST Api's good for?• Real World Examples

Definition

• Representational State Transfer (REST) is an architectural style that abstracts the architectural elements within a distributed hypermedia system.[1] REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.[2] REST has emerged as a predominant web API design model

• What is REST?

• REpresentational State Transfer. It describes how one system can communicate state with another. One example would be the state of a product (its name, description etc) represented as XML, JSON, or plain text. The generalised idea of state is termed a resource.

• REST is commonly associated with the web services interface since HTTP is by far the most common carrier protocol.

• REST is not HTTP. It uses HTTP because in its most general form REST exists to assist a machine in mapping the concept of a verb against an arbitrary collection of nouns. HTTP contains a useful set of generic verbs (GET, PUT, PATCH etc) that can applied to arbitrary nouns expresssed as URIs using HTTP e.g. GET http://example.org/Product(54).

• REST is not really a technology in itself, but more an architectural pattern. REST is very simple and just involves using plain XML or JSON as a communication medium, combined with URL patterns that are "representational" of the underlying system, and HTTP methods such as GET, PUT, POST and DELETE

Definition

–Contracts?–CRUD?– State?– Schema/WSDL?

Practically Speaking

JSON (could be XML)HTTP (Crud)Stateless (kinda)

Competing Technologies?

– SOAP?– JDBC?– TCP?– WebSockets?

Reasons for ReST

• Tech– Decoupling– Performance?– Portability - OS's, PLatform– Simplicity

Reasons for Rest

• Business– Publically preesenting their apis's– Mashups– Monetizing

Everybody's Doing ReST

• Real World Examples– Google Books:

• https://developers.google.com/books/docs/v1/using#WorkingBookshelves– Twitter

• https://dev.twitter.com/docs/api/1.1

– open BBY: • https://bbyopen.com/

• Reference - more API's– http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI/RESTcontents– http://dev.twitter.com/doc/post/statuses/destroy/:id– http://www.salesforce.com/us/developer/docs/api_rest/index.htm– http://www.flickr.com/services/api/– http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteEndpoints.html– http://www.3scale.net/– http://scottfrederick.github.io/springdoclet/ also https://github.com/kliniki-online

2. Designing a ReST API

• Design your URI's• Conundrums• Payload• Frameworks• Example

Design your URI's

• SEO Considerations• Verb Considerations

Conundrums

• PUT vs. Post arguments, idempotency• Versioning

– SEO– Header vs URL versioning

Payload

• Normalizing Your Requests/Responses– JSEND– http://labs.omniti.com/labs/jsend

• Headers & Mime Types• Error Handling

Frameworks

• Restlet• NodeJS• Spring MVC• Resteasy• Jersey• Jax• Grails• Ruby Rails• PHP, Python, Perl• C#• Don't get me started on caching . . .

Use Patterns (Observer, Facade, MVC etc.)

Tools

• Firebug• Rest PLugins• Fiddler• Wireshark• JSLint• curl

Example

• RestNotes Grails Application

3. Documenting a ReST API

• Why Document?• Tools• Examples

Why Document?

• Consumers of your API• Querying the rest API

Tools

• Javadocs?• Realtime Docs• Contract considerations• There are some new and totally cool tools

– 3Scale - commercial– RestletDocs– Swagger– Apiary– Mashery– Enunciate

• Some are just markup tools - @API• http://mestachs.wordpress.com/2012/08/06/rest-api-

documentation/

Examples

• Apidocs for Grails• Swagger for Grails/JAX

4. Testing a ReST API

• Salient Discussion Points– Unit testing– Integration Testing– Functional Testing– Acceptance Testing– BDD– TDD?– Test Server– Sharable tests -- dev, qa, consumers

5. UI Considerations

• Bridge Building• Accessing ReST• Fat Clients are Dead,

Long Live Fat Clients

Bridge Building

• Get that test data going• What gets computed on either side?

– A "pure" api vs catering to UI?

Accessing ReST

• Each language/library can use ReST in their Repository

• HTTP libraries in Java, etc.

Fat Clients are Dead, Long Live Fat Clients

• Backend ReST consumption• Fat Javascript Clients• Mobile Apps!• DualMVC idea --its a full blown

6. Final Thoughts

1. What is a ReST API?2. Designing3. Documenting4. Testing5. UI Considerations6. Final Thoughts

Questions?

Thank You

Kingsoft OfficeMake Presentation much more fun

Bil MowryIvy Street Technology LLC

bil.mowry@yahoo.comblog: 10kdev.net@bilmowry

Thanks to the sponsors of this camp!