From ZERO to REST in an hour

from ZERO
to REST in an hour
@CiscoDevNet

Overview
 understand the basics around RESTful Web APIs
 HTTP : HyperText Transfer Protocol
 REST : Representational State Transfer
 API : Application Programming Interface
 use Postman to interact with Web APIs
 Postman Chrome App : get it at http://www.getpostman.com/
 no pre-requisites
 worth mentionning : no coding experience required

DevNet
 Cisco’s Developer Community
Program
 commitment : create a vibrant
Developer ecosystem delivering
innovative applications with deep
API integrations into Cisco
platforms.
 resources for ITPros and Devs
 https://developer.cisco.com
 learning labs
 sandboxes
3

/Cisco/DevNet/SteveSfartz
 API Evangelist @CiscoDevNet
 Tropo & Cisco Spark APIs
 code addict, any but #golang better ;-)
 live in France, all around EMEA
 hosted @PIRL
 Paris Innovation Center & Research Lab
 twitter://@SteveSfartz
 github://ObjectIsAdvantag
“vision without
execution is
hallucination”
-- Thomas Edison
stsfartz@cisco.com

HTTP under the hood
programming the web
5

HyperText Transfer Protocol (HTTP)
 a core protocol for internet communications
 a request / response protocol
 synchronous
 stateless
6
GET /index.htm HTTP/1.1
HTTP 200 OK
Client Server

HTTP Request : Protocol
 HTTP 1.0 is what the Web has been built upon historically, still used by
some embedded devices and enterprise proxies
 HTTP 1.1 is the current, generally used HTTP protocol version
 HTTP/2 is the next version of HTTP, although known as SPeeDY,
multiplex & bidirectional communications + header compression
 the HTTP protocol defines the request / response interaction principles
(methods, headers, status codes, body contents …)
7

URL - Uniform Resource Locator
 scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
 http://github.com/CiscoDevNet/spark-webhooks-sample
 server: github.com, port defaults to 80, path: /CiscoDevNet/spark-webhooks-sample
 https://github.com/CiscoDevNet/spark-webhooks-sample
 encrypted communication issued over TLS, port defaults to 443
 https://github.com:9090/CiscoDevNet?page=2
 query the server to serve the 2nd page of results, TLS connection on port 9090
8

Accessing github under the hood
9
GET /CiscoDevNet HTTP/1.1 Accept: text/html :443
HTTP 200 OK
browser github.com
method path protocol
status code
https://github.com/CiscoDevNet
portheaders
URL:
response body
HTTP
request
HTTP
response
host
HTML page

Hands on
HTTP under the hood with Postman
10

Install Postman
 free tool to forge API requests, examine responses
 easy to replay requests, organize in collections
 http://getpostman.com
11

13
method
url
headers
status
response
content-type

RESTful Web APIs
 Web API
 a way for two systems to communicate
 two major types : REST and SOAP
 REST
 stands for Representational State Transfer (REST)
 an architecture style for designing communications over HTTP
 RESTful Web APIs
 communicate by leveraging all the expressiveness of the HTTP protocol
 Methods, Status codes, Content-Types, Headers
15

HTTP Request : Methods
 GET – retrieve contents from the server
 HEAD – only get the HTTP headers & status code (don't GET the body)
 PUT – update content
 PATCH – partial update
 POST – create content
 DELETE – delete content
 OPTIONS – retrieve contextual information before issuing a request
 check W3C RFC 7230-7 to get an exhaustive list of HTTP/1.1 methods
16

HTTP Request / Response : Body
 data sent to or retrieved from the server
 HTML
 plain text
 JSON
 XML
 SOAP (XML format for advanced interactions)
 Binary data (single file, blob)
 Multi-part contents (files)
 Web APIs typically exchange JSON, XML, binary, and raw text
 GET and DELETE requests do not provide a body
17

HTTP Response : Status Codes
 1xx - Information
 100 Continue
 2xx - Success
 200 OK, 201 Created, 204 No Content
 3xx - Redirection
 301 Moved permanently, 304 Not modified
 4xx - Client error
 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
 5xx - Server error
 500 Internal Error, 501 Not Implemented, 503 Service Unavailable
 interactive map at www.restapitutorial.com/httpstatuscodes.html
18

Hands on
list repositories with the github API
19

20
https://github.com/CiscoDevNet

21
API documentation https://developer.github.com/v3/

JSON syntax
 square brackets for lists
 curly braces for objets
 name/value pairs for properties,
separated by commas
 pick an online editor
http://codebeautify.org/jsonviewer
http://www.jsoneditoronline.org
23

HTTP Request / Response : Headers
 define the operating parameters of an HTTP transaction (req/resp)
 optional key-value pairs
 Accept-Language: en-US, fr
 so that the server can adapt the content locale, [request only]
 Accept: application/json, application/xml
 types of data supported by the client, [request only]
 Content-Type: application/json
 type of the request body provided in the request, [request | response]
 User-agent, Cache control, Authorization…
25

REST Authentication
 None: the Web API resource is public, anybody can place call.
Generally the case for GET methods, rarely for POST, PUT, DELETE.
 Basic HTTP: a username and password are passed to the server in an
encoded string. Part of the HTTP protocol.Passed with each API call.
 Authorization: Basic ENCODEDSTRING
 Token: a secret generally retrieved from the Web API developer portal.
 The keyword may change from one Web API to another: Bearer, token..
 Passed with each API call.
 OAuth: A sequence flow is initiated to retrieve an access token from an
Identity Provider. The token is then passed with each API call.
 Open standard. User rights are associated to the token (OAuth scope).
 The token is short-live, can be revoked and re-issued via a refresh token. 26

Hands on
authenticated request (Basic HTTP)
27

Signup for a free Github account
 https://github.com/join
 free account by default
 reply to github confirmation email
Welcome to the developers
community !
28

Resetting Authentication in Postman
 resend latest authenticated request
 check custom Header X-RateLimit-Limit is set to 5000
 go the Headers tab, remove the Authentication header
 go to Authorization tab, choose No Auth
 resend request, custom Header X-RateLimit-Limit is now set to 60 31

Hands on
authenticated request (token)
32

Github Token based Authentication
1. go to Settings, 2. select Personal access tokens
3. select scopes and generate token
33
1
3
2

Github Token based authentication
 generate a new token
34

Github Token based authentication
 set the Authorization Header in Postman
 keyword vary among Web APIs, « token » to authenticate against Github
35

401 Unauthorized
 replace the token value with « Whatever »
36

RESTful Web APIs sumup
a typical workflow
37

RESTful Web APIs sumup
 method
 GET, POST, PUT, DELETE
 URL scheme
 http://{SERVER}/api/v1/schema/entity/3
 authentication
 None, Basic HTTP, token, OAuth
 headers
 Content-Type: application/json
 request / response body
 JSON or XML contents exchanged between the client and the Web API
38

Logic to add comments to a Github gist
41
HTTP
Client
Github
API
AddCommentToGist (gistID, comment)
CommentID
GetGistsForUser (GithubAccout)
GistsList
RemoveComment (commentID)
Ack

Equivalent RESTful Web API flow
42
POST /gists/:gistID/comments
201 Created { comment }
HTTP
Client
Github
API
GET /users/:username/gists
200 OK { gists}
DELETE /gists/:gistID/comments/:commentID
204 No Content

 Create a POST method, with JSON Body contents
 Do not forget to set the Authorization Header
44

 new comment identifier may be retreived from the response Body
45
commentID

 but also from the Location header : good REST practice
46
commentID

HTTP clients
 a tool to initiate calls to an HTTP Server
 Note : strictly equivalent to Web Client / Web Server
 any Web Browser
 via a user-friendly User Interface
 Postman, Chrome Developer Toolbar, IFTTT, Zapier, Built.io
 from the command line
 telnet, curl
 any programming languages
 Python, Javascript, Java, Ruby, PHP, C#, Go…
48

To go further
 join the Cisco developers community
 https://developer.cisco.com/
 take a free online Coding Lab
 https://learninglabs.cisco.com/labs/tags/Coding
 21 learning labs proposed
 REST, Python, Parsing JSON, RAML, Git
 meet DevNet at a physical event: conferences, hackathons…
 https://developer.cisco.com/site/devnet/events-contests/events/
49

Thank you
twitter: @CiscoDevNet
https://developer.cisco.com

To go further
interacting from the command line
51

curl
 HTTP from the command line
 part of linux operating systems
 Windows users
1. PowerShell
2. or git for Windows comes with
a bash, with curl command
52
$ curl -v -X GET http://github.com/CiscoDevNet
* Trying 192.30.252.131...
* Connected to github.com (192.30.252.131) port 80
(#0)
> GET /CiscoDevNet HTTP/1.1
> Host: github.com
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Content-length: 0
< Location: https://github.com/CiscoDevNet
< Connection: close
<
* Closing connection 0

curl
 Part of linux operating systems
53
* Trying 192.30.252.131...
(#0)
> Host: github.com
> Accept: */*
>
< Content-length: 0
< Connection: close
<

curl
54
* Trying 192.30.252.131...
(#0)
> Host: github.com
> Accept: */*
>
< Content-length: 0
< Connection: close
<
HTTP
request

curl
55
* Trying 192.30.252.131...
(#0)
> Host: github.com
> Accept: */*
>
< Content-length: 0
< Connection: close
<
HTTP
response

telnet
 TCP interactive client
 Part of all operating systems
 Universal but not HTTP friendly
 Not HTTPS capable
56
$ telnet github.com 80
GET /
HTTP/1.1 301 Moved Permanently
Content-length: 0
Location: https:///
Connection: close

To go further
calling Web APIs from Python
57

API calls in Python
 Python 3, with the requests module
import requests
url = "https://api.github.com/users/DevNet"
headers = {
'cache-control': "no-cache"
}
response = requests.request("GET",url, headers=headers)
print(response.text)
58

API calls in Python
 Python 3, with the http.client module
import http.client
conn = http.client.HTTPSConnection("api.github.com")
headers = {
'cache-control': "no-cache"
}
conn.request("GET", "/users/DevNet", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
59

From ZERO to REST in an hour

More Related Content

What's hot (20)

Similar to From ZERO to REST in an hour (20)

More from Cisco DevNet (20)

Recently uploaded (20)

From ZERO to REST in an hour

Editor's Notes