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

1. TESTING AND
DOCUMENTING
PRAGMATIC/
RESTFUL
WEB API
Arul Kumaran
Author of Restler - a Pragmatic/RESTful API framework

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

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. WHAT IS RESTFUL/
PRAGMATIC API
one leads to more
‣ What is Web API?
‣ What is REST?
‣ What is Pragmatic API?

5. WEB APPLICATION
PROGRAMMING INTERFACE
When it all started
Web is mainly used for
human to human Data + Presentation
communication using
HTML as the medium =
which is Data and
Presentation put
together

6. WEB APPLICATION
PROGRAMMING INTERFACE
Then the change
By just sending pure
data as XML, JSON etc, Data Presentation
It can interpreted by a
client or another server
in a meaningful way
opening the door of
possibilities

7. REPRESENTATIONAL STATE
TRANSFER
Set of constraints ‣
‣ Client-server
‣ Stateless ‣ Code on demand
(optional)
‣ Cacheable
‣ Uniform Interface
‣ Layered system

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_provided
413 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. 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

10. DOCUMENTING API
Why it is needed?
‣ Missing presentation
layer makes it difficult
to discover and
navigate around API

11. DOCUMENTING API
How to do it?
‣ Where to write it?
‣ How to maintain it in
sync with ever
changing API

12. MEET SWAGGER
Start 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. MEET SWAGGER UI
Or 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. 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. 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. END RESULT

17. MEET LURACAST
RESTLER
Write OO PHP ‣
‣ Well written, Well
commented PHP
API becomes Well ‣ RESTler Explorer
provides the
written, Well
documentation and
documented Web
testing interface
API

18. OBJECT ORIENTED PHP
<?php
use
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. API EXPLORER

20. BEHAVIOR DRIVEN API
DEVELOPMENT
Scenario:
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. WHAT,WHY AND HOW
RECAP
‣ What is
RESTful/Pragmatic API
‣ Why it requires
documentation and testing
‣ How to do
documentation and testing

22. ABOUT ME
@_Arul @Luracast