Kazoo APIs are an example of a restful web-service. They are APIs are provided over HTTP/HTTPS. Kazoo APIs mostly uses the JavaScript Object Notation (JSON) data format for most payloads!
15. #kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
16. #kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
/v1/
17. #kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
/v1/
/v1/accounts/
18. #kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
/v1/
/v1/accounts/
/v1/accounts/C1234/
19. #kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
/v1/
/v1/accounts/
/v1/accounts/C1234/
/v1/accounts/C1234/users/
20. #kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
/v1/
/v1/accounts/
/v1/accounts/C1234/
/v1/accounts/C1234/users/
/v1/accounts/C1234/users/U3456/
21. #kazoocon14
How do we tell the server
what to do with the resource
we identified?
22. #kazoocon14
HTTP Verbs or Methods
GET - /v1/accounts/C1234/users/
PUT - /v1/accounts/C1234/devices/
+ data payload
POST /v1/accounts/C1234/users/U1112
+ data payload
DELETE - /v1/accounts/C1234/users/U1112
23. Verbs for interacting with collections
#kazoocon14
GET - /v1/accounts/C1234/users/
PUT - /v1/accounts/C1234/users/
+ data payload
24. #kazoocon14
Verbs for interacting with entities
GET - /v1/accounts/C1234/users/U1112
POST /v1/accounts/C1234/users/U1112
+ data payload
DELETE /v1/accounts/C1234/users/U1112
25. #kazoocon14
HTTP Response codes
2xx - successful request!
200 - means the request was successful
201 - Entity was created
4xx - you messed up!
401 - unauthorized (check your auth token)
404 - entity or endpoint doesn't exist.
5xx - server messed up!
500 - generic server error
26. #kazoocon14
HTTP headers
Headers are used to set parameters used in
processing the request.
Example:
X-Auth-Token: <your auth token>
Content-Type: application/json
36. #kazoocon14
In the API, we always have a “data” object which
contains the payload.
{
“data” : {
“parameters_for_resource” : “some value”
}
“metadata_stuff” : …
}
43. #kazoocon14
• The URI is a “noun” which Identifies a specific resource.
• The HTTP method is a “verb” which defines what type of action we
want to take against the resource.
• The contents of the payload is a JSON object.
45. Tools for exploring Kazoo APIs
#kazoocon14
• Kazoo UI, Developer tools
• Curl – Command Line Tool
• Postman – Browser based.
• SDKs (Software Development Kit)
46. Tools for exploring Kazoo APIs
#kazoocon14
• Kazoo UI, Developer tools
http://kazooui.kazoocon.com
• Curl – Command Line Tool
• Postman – Browser based.
• SDKs (Software Development Kit)
47. #kazoocon14
Authentication Tokens
Temporary “Security tokens” used to authenticate clients.
How to get one:
credentials = an md5 hash of the string username:password
echo -n “user:pass” | md5
PUT http://api.sandbox.2600hz.com:8000/v1/user_auth
{ “data”: { “credentials” : “12345678”, “realm” : “your.realm.com” }}
or
{ “data”: { “credentials” : “12345678”, “account_name” : “account_name”}}
PUT http://api.sandbox.2600hz.com:8000/v1/api_auth
{ “data” : { “api_key” : “YOUR_API_KEY” }}
NOTE: you can get API key with GET -/v1/accounts/<Account_ID>/api_key
48. Tools for exploring Kazoo APIs
#kazoocon14
• Kazoo UI, Developer tools
• Curl – Command Line Tool
• Postman – Browser based.
• SDKs (Software Development Kit)
49. Tools for exploring Kazoo APIs
#kazoocon14
• Kazoo UI, Developer tools
• Curl – Command Line Tool
• Postman – Browser based.
• SDKs (Software Development Kit)
50. Tools for exploring Kazoo APIs
#kazoocon14
• Kazoo UI, Developer tools
• Curl – Command Line Tool
• Postman – Browser based.
• SDKs (Software Development Kit)
Good morning!
Welcome to kazoo con!
This session we are going to introduce the KAZOO APIs. and show you some easy ways you can explore the APIs
30 seconds
When we talk about APIs, were are talking about an interface provided by a server that is intended for use by applications.
This interface provides a predictable and simple method for applications to connect and interact with remote services.
Developers can use APIs to leverage external services and add complex functionality to their applications with just a few lines of code.
An API is like a bolt.
You use bolts to build something useful.
Your application is like a wrench.
A bolt has specific parameters like size and shape that wrenches need to conform to.
We provide the standard sizes and shapes of our bolts,
You can innovate to build a better wrench as long as you conform to the specification of our bolt.
Kazoo APIs are based on the Rest Architecture. The philosophy behind Kazoo APIs is “what would the web do?”
The protocol which is used to access the API is HTTP/HTTPS.
Which means in most cases…
So in this diagram we have a basic client server architecture.
The Client of an API is an application.
The client sends a request to the server.
The server returns a response to the request.
The difference between an API and a website is that APIs just return raw data instead of an pretty html page.
This request and response dialog is called a transaction.
Requests are just the mechanism for client application to view and interact with specific resource on the server.
Like a device, an account, a phone number, a user.
We handle resources in two ways in our API….
The first way is as COLLECTIONS.
All accounts,
All users under an account…
Individual account, individual user…
Every entity has an ID we can refer to it by.
URIs are just a string which identifies a resource.
This string is a “chain” of resources, which combine to determine which specific resource is being referenced.
The URI is here to tell the server what THING we want to interact with.
So to understand how a URI works, lets break apart this chain and step through it link by link.
The first link in the chain is the base URL.
The base URL identifies the location of the server on the internet which provides access to interact with the API.
The next link is the version.
V1 just means version 1. This indicates the VERSION of the API we are interacting with.
NEXT IN OUR CHAIN is accounts
This is an endpoint. An endpoint is a collection of one the type of resource.
IF WE APPEND AN ID AFTER THE ACCOUNT ENDPOINT WE ARE IDENTIFYING A SPECIFIC ACCOUNT ENTITY.
IF WE ADD USER TO THE CHAIN WE ARE IDENTIFYING a collection of the USERS IN THIS ACCOUNT.
IF we add a USER_ID to the chain we are identifying a specific user on this account.
HTTPs provides methods which determine the types of actions that should be taken against the resource identified in the URI.
Rest uses 4 basic verbs in HTTP that are used to determine which specific actions should be taken.
Use of verbs is specific to the type of entity being referenced.
GET with the URI of a resource endpoint will get a collection from this endpoint.
PUT is used to create a new resource in the collection.
GET - against a URI with a resource ID, will return a full representation of this resource. EG: GET THIS SPECIFIC USER ON THIS ACCOUNT
POST is an update VERB which updates the contents of the entity with the data payload included in the request. EG: Update this specific user on this account.
DELETE does just what it sounds like it does, it delete the entity.
Responses to these requests from the server contain a response code which tells you the status of the transaction.
2xx is a success response.
4xx is a client side problem (invalid request for example)
5xx means the server encountered an error
HTTP protocol uses headers to describe and define values which determine how the request is formatted.
EXAMPLE: You can specify things like the content type which defines the data format of the payload you are sending.
The API abstracts all the resources, so we can retrieve them in an expected format.
The actual entity referred to could use any number of ways to store its data, but this will always be delivered by the API in a payload format that is uniform.
Json is an easily readable, widely supported format for storing data in nested structures.
MOST OF THE DATA IN JSON IS REPRESENTED AS KEY VALUE PAIRS
A KEY IS JUST A NAME for the parameter
VALUES CAN BE ANY OF THE AVAILABLE DATA TYPES.
Json lets you encode common datatypes that exist all in mainstream programming languages.
The envelope of a JSON object is contained inside a base object.
You can pretty much represent anything using JSON objects.
Kazoo API payloads will always have a data object which contains the parameters related to a resource.
Out side this object we can add some meta data if required by a request/response.
This is an actual GET message.
This is submitted with no payload included.
You can see a request line which contains the HTTP VERB, a request URI, the HTTP version and a HOST.
This request also includes some headers like the X-auth-token and Content-Type
And this is response we get back with the data requested by the get.
You can see the 200 OK in the response line indicating successful request.
The response headers, and a data payload with the data requested by the Get command.
This is an example of an HTTP put.
This type of request includes a payload in JSON format containing the data needed by the server to handle the request.
Instead of GET the verb here is PUT, the URI is the user_auth endpoint.
This is the response to the put request.
You can see the response code here is 201 which means Put was successful and an auth token was created.
The response payload contains the account_id for the auth token as well as the Auth_token returned.
So now that have the fundamentals defined…
and if it is a collection or an entity.
- The specific VERB you can use is dependent on this URI referencing
a resource or a collection.
One of the easiest way to get started, is through the Developers App (must be enabled), here’s how, let’s do a sample query of our own account!
From this first example, the URI is :8000/v1/, the re
“So we have a few ways to interact with the Apis. The easiest to get started with would be the Developer tools app in Kazoo. This is a Web Based REST client we built for testing and exploring our basic APIs.
*OTHER SCREEN, LIVE*
Kazoo UI
Log into kazoo-ui
Turn on Developer App
Do simple query of account
One of the easiest way to get started, is through the Developers App (must be enabled), here’s how, let’s do a sample query of our own account!
From this first example, the URI is :8000/v1/, the re
“So we have a few ways to interact with the Apis. The easiest to get started with would be the Developer tools app in Kazoo. This is a Web Based REST client we built for testing and exploring our basic APIs.
*OTHER SCREEN, LIVE*
Kazoo UI
Log into kazoo-ui
Turn on Developer App
Do simple query of account
One of the easiest way to get started, is through the Developers App (must be enabled), here’s how, let’s do a sample query of our own account!
From this first example, the URI is :8000/v1/, the re
“So we have a few ways to interact with the Apis. The easiest to get started with would be the Developer tools app in Kazoo. This is a Web Based REST client we built for testing and exploring our basic APIs.
*OTHER SCREEN, LIVE*
Kazoo UI
Log into kazoo-ui
Turn on Developer App
Do simple query of account
One of the easiest way to get started, is through the Developers App (must be enabled), here’s how, let’s do a sample query of our own account!
From this first example, the URI is :8000/v1/, the re
“So we have a few ways to interact with the Apis. The easiest to get started with would be the Developer tools app in Kazoo. This is a Web Based REST client we built for testing and exploring our basic APIs.
*OTHER SCREEN, LIVE*
Kazoo UI
Log into kazoo-ui
Turn on Developer App
Do simple query of account