Development Lessons

1. Development Lessons of ReST APIs Presented by Bil Mowry Ivy Street Technology LLC

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

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

4. Major Points • What is a ReST API? • Designing • Documenting • Testing • UI Considerations • Final Thoughts

5. 1. What is a ReST API? • Definition • What are ReST Api's good for? • Real World Examples

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

7. Definition • Contracts? • CRUD? • State? • Schema/WSDL?

8. Practically Speaking JSON (could be XML) HTTP (Crud) Stateless (kinda)

9. Competing Technologies? • SOAP? • JDBC? • TCP? • WebSockets?

10. Reasons for ReST • Tech • Decoupling • Performance? • Portability - OS's, PLatform • Simplicity

11. Reasons for Rest • Business • Publically preesenting their apis's • Mashups • Monetizing

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

13. 2. Designing a ReST API • Design your URI's • Conundrums • Payload • Frameworks • Example

14. Design your URI's • SEO Considerations • Verb Considerations

15. Conundrums • PUT vs. Post arguments, idempotency • Versioning • SEO • Header vs URL versioning

16. Payload • Normalizing Your Requests/Responses • JSEND • http://labs.omniti.com/labs/jsend • Headers & Mime Types • Error Handling

17. 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.)

18. Tools • Firebug • Rest PLugins • Fiddler • Wireshark • JSLint • curl

19. Example • RestNotes Grails Application

20. 3. Documenting a ReST API • Why Document? • Tools • Examples

21. Why Document? • Consumers of your API • Querying the rest API

22. 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/

23. Examples • Apidocs for Grails • Swagger for Grails/JAX

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

25. 5. UI Considerations • Bridge Building • Accessing ReST • Fat Clients are Dead, Long Live Fat Clients

26. Bridge Building • Get that test data going • What gets computed on either side? • A "pure" api vs catering to UI?

27. Accessing ReST • Each language/library can use ReST in their Repository • HTTP libraries in Java, etc.

28. Fat Clients are Dead, Long Live Fat Clients • Backend ReST consumption • Fat Javascript Clients • Mobile Apps! • DualMVC idea --its a full blown

29. 6. Final Thoughts • What is a ReST API? • Designing • Documenting • Testing • UI Considerations • Final Thoughts Questions?

30. Thank You Bil Mowry Ivy Street Technology LLC bil.mowry@yahoo.com blog: 10kdev.net @bilmowry KingsoftOffice Make Presentation much more fun

31. Thanks to the sponsors of this camp!