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" } ] } ] }, //...

END RESULT

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