TESTING AND DOCUMENTING PRAGMATIC/
RESTFUL WEB API
Arul KumaranAuthor of Restler - a Pragmatic/RESTful API framework
SETTING THE CONTEXT RIGHT
Reminding myself:
‣ I’m presenting in a JavaScript User Group
‣ I need to keep it short and simple at least to begin with
WHAT,WHY AND HOW
? is the beginning
‣What is RESTful/Pragmatic API
‣Why it requires documentation and testing
‣ How to do documentation and testing
WHAT IS RESTFUL/PRAGMATIC API
one leads to more
‣What is Web API?
‣What is REST?
‣What is Pragmatic API?
WEB APPLICATION PROGRAMMING INTERFACE
When it all started
Web is mainly used for human to human communication using HTML as the medium which is Data and Presentation put together
Data Presentation+
=
WEB APPLICATION PROGRAMMING INTERFACE
Then the change
By just sending pure data as XML, JSON etc, It can interpreted by a client or another server in a meaningful way opening the door of possibilities
Data Presentation
REPRESENTATIONAL STATE TRANSFER
Set of constraints
‣Client-server
‣ Stateless
‣Cacheable
‣ Layered system
‣
‣Code on demand (optional)
‣Uniform Interface
WHY PRAGMATIC WEB API
REST is not easy500 Internal Server Error500 Internal Server Error
true
is_accept_ok
false
false
true
is_request_ok
false
uri_too_long
allowed_methods
content_types_accepted:handler
is_authorized
is_forbidden
valid_content_headers
content_types_accepted
valid_entity_length
options
true
false405 Method Not Allowed405 Method Not Allowed
If-Modified-Since exists?generate_etag
If-None-Match exists?Last-Modified >
false
If-Unmodified-Since exists?
If-Match exists?
generate_etag
encodings_provided
true
Accept-Encoding exists?charsets_provided
true
Accept-Charset exists?languages_provided
true
Accept-Language exists?content_types_provided
Accept exists?
false
true413 Request Entity Too Large413 Request Entity Too Large
true
false
415 Unsupported Media Type415 Unsupported Media Type
false
true501 Not Implemented501 Not Implemented
false
false
true200 OK200 OK
true
false
400 Bad Request400 Bad Request
false
true
true
true
true
false
false
406 Not Acceptable406 Not Acceptable
true
false
false
false
false
false
true
false
true
false
true
403 Forbidden403 Forbidden
401 Unauthorized401 Unauthorized
414 Request URI Too Long414 Request URI Too Longfalse
true
true
true
false
true
true
true
false
true
false
false
true
E8
B2
B12
B10
B5
B4
B3
B8
B6
B7
B9
F12E12
E11D11
D10
G7
C9
C10
F7
F6E6
E5D5
D4C4
C3
DOCUMENTING API
Why it is needed?
‣One Creates API and Another consumes
‣ There should be an easy way with out sitting next to each other
DOCUMENTING API
Why it is needed?
‣Missing presentation layer makes it difficult to discover and navigate around API
DOCUMENTING API
How to do it?
‣Where to write it?
‣How to maintain it in sync with ever changing API
MEET SWAGGER
Start with JSON
‣Write how your api will work
‣What it takes in
‣What it spits out
‣
‣ Build your API, Documentation and Testing interface in one go
MEET SWAGGER UI
Or start with server
‣ It produces a resource list
‣ Declares each API
‣ Available operations
‣ Parameters
‣ Request Response models
‣ Error responses and description
‣
‣ Swagger UI can use that to produce a UI for testing & documentation
RESOURCE LIST
{"apiVersion" : "0.2", "swaggerVersion" : "1.1", "basePath" : "http://petstore.swagger.wordnik.com/api", "apis" : [ { "path" : "/api-docs.{format}/user", "description" : "" }, { "path" : "/api-docs.{format}/pet", "description" : "" }]}
It’s like site-map to
your API
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" } ] } ] }, //...
MEET LURACAST RESTLER
Write OO PHP
‣Well written, Well commented PHP API becomes Well written, Well documented Web API
‣
‣ RESTler Explorer provides the documentation and testing interface
OBJECT ORIENTED PHP<?phpuse Luracast\Restler\RestException;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')); }
API EXPLORER
BEHAVIOR DRIVEN API DEVELOPMENT
Scenario: Multiply 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
Gherkin
Savoury pickled cucumber
WHAT,WHY AND HOW
RECAP
‣What is RESTful/Pragmatic API
‣Why it requires documentation and testing
‣ How to do documentation and testing
ABOUT ME
@_Arul @Luracast