Testing and Documenting Pragmatic / RESTful Web API


Published on

Explains web api and why and how to do the documentation and testing. Covers behaviour driven development (BDD) and the tools that come in handy

Here are the important URL's from the presentation

- https://github.com/wordnik/swagger-ui
- https://github.com/Luracast/Restler
- https://github.com/Luracast/Restler-API-Explorer

Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Testing and Documenting Pragmatic / RESTful Web API

  1. 1. TESTING AND DOCUMENTING PRAGMATIC/ RESTFUL WEB API Arul KumaranAuthor of Restler - a Pragmatic/RESTful API framework
  2. 2. SETTING THE CONTEXT RIGHTReminding myself:‣ I’m presenting in a JavaScript User Group‣ I need to keep it short and simple at least to begin with
  3. 3. WHAT,WHY AND HOW? is the beginning‣ What is RESTful/Pragmatic API‣ Why it requires documentation and testing‣ How to do documentation and testing
  4. 4. WHAT IS RESTFUL/ PRAGMATIC APIone leads to more‣ What is Web API?‣ What is REST?‣ What is Pragmatic API?
  5. 5. WEB APPLICATIONPROGRAMMING INTERFACEWhen it all startedWeb is mainly used forhuman to human Data + Presentationcommunication usingHTML as the medium =which is Data andPresentation puttogether
  6. 6. WEB APPLICATIONPROGRAMMING INTERFACEThen the changeBy just sending puredata as XML, JSON etc, Data PresentationIt can interpreted by aclient or another serverin a meaningful wayopening the door ofpossibilities
  7. 7. REPRESENTATIONAL STATE TRANSFERSet of constraints ‣‣ Client-server‣ Stateless ‣ Code on demand (optional)‣ Cacheable ‣ Uniform Interface‣ Layered system
  8. 8. WHY PRAGMATIC WEB API REST is not easy is_request_ok 500 Internal Server Error B2 false true false is_forbidden Accept exists? 403 Forbidden B3 C3 true false true true is_authorized content_types_provided Accept-Language exists? 401 Unauthorized B4 C4 D4 false true false false true false content_types_accepted:handler languages_provided Accept-Charset exists? 400 Bad Request B5 D5 E5 true true false false true false content_types_accepted charsets_provided Accept-Encoding exists?415 Unsupported Media Type B6 E6 F6 true true false false true false valid_entity_length encodings_provided413 Request Entity Too Large B7 F7 G7 true true false true false valid_content_headers is_accept_ok 501 Not Implemented B8 406 Not Acceptable E8 true false true false options If-Match exists?
  9. 9. DOCUMENTING APIWhy it is needed?‣ One Creates API and Another consumes‣ There should be an easy way with out sitting next to each other
  10. 10. DOCUMENTING APIWhy it is needed?‣ Missing presentation layer makes it difficult to discover and navigate around API
  11. 11. DOCUMENTING APIHow to do it?‣ Where to write it?‣ How to maintain it in sync with ever changing API
  12. 12. MEET SWAGGERStart with JSON ‣‣ Write how your api will work ‣ Build your API,‣ What it takes in Documentation and Testing interface in one‣ What it spits out go
  13. 13. MEET SWAGGER UIOr start with server ‣‣ It produces a resource list‣ Declares each API ‣ Swagger UI can use that to ‣ Available operations produce a UI for testing & ‣ Parameters documentation ‣ Request Response models ‣ Error responses and description
  14. 14. RESOURCE LIST{"apiVersion" : "0.2", "swaggerVersion" : "1.1", "basePath" : "http://petstore.swagger.wordnik.com/api", "apis" : [ { "path" : "/api-docs.{format}/user", "description" : "" }, It’s like { site-map to "path" : "/api-docs.{format}/pet", your API "description" : "" }]}
  15. 15. API DESCRIPTION{"apiVersion" : "0.2", "swaggerVersion" : "1.1", "basePath" : "http://petstore.swagger.wordnik.com/api","resourcePath" : "/pet", "apis" : [ { "path" : "/pet.{format}/{petId}", "description" : "Operations about pets", "operations" : [ { "httpMethod" : "GET", "summary" : "Find pet by ID", "notes" : "Returns a pet based on ID", "responseClass" : "Pet", "nickname" : "getPetById", "parameters" : [ { "name" : "petId", "description" : "ID of pet that needs to be fetched", "paramType" : "path", "required" : true, "allowMultiple" : false, "dataType" : "string" } ], "errorResponses" : [ { "code" : 400, "reason" : "Invalid ID supplied" }, { "code" : 404, "reason" : "Pet not found" } ] } ] }, //...
  16. 16. END RESULT
  17. 17. MEET LURACAST RESTLERWrite OO PHP ‣‣ Well written, Well commented PHP API becomes Well ‣ RESTler Explorer provides the written, Well documentation and documented Web testing interface API
  18. 18. OBJECT ORIENTED PHP<?phpuse  LuracastRestlerRestException;use  DB_Session;class  Authors{        public  $dp;        /**          *  @status  201          *          *  @param  string  $name    {@from  body}          *  @param  string  $email  {@type  email}  {@from  body}          *          *  @return  mixed          */        function  post($name,  $email)        {                return  $this-­‐>dp-­‐>insert(compact(name,  email));        }
  19. 19. API EXPLORER
  20. 20. BEHAVIOR DRIVEN API DEVELOPMENTScenario:  Multiply Gherkin        Given  that  "n1"  is  set  to  "10"        And  "n2"  is  set  to  "5"        When  I  request  "/examples/_002_minimal/math/multiply/{n1}/{n2}"        And  the  response  is  JSON        And  the  response  has  a  "result"  property        And  the  "result"  property  equals  50 Savoury pickled cucumber
  21. 21. WHAT,WHY AND HOWRECAP‣ What is RESTful/Pragmatic API‣ Why it requires documentation and testing‣ How to do documentation and testing
  22. 22. ABOUT ME@_Arul @Luracast