kazoocon 2014 - introduction to kazoo apis!
DESCRIPTION
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!TRANSCRIPT
PRESENTED BY:
INTRODUCTION TO KAZOO APIs
Sean & Ricky
#kazoocon14
What is an API?
#kazoocon14
ApplicationProgrammingInterface
#kazoocon14
An API as a bolt.
#kazoocon14
REST
Kazoo APIs are an example of a RESTFul web-service.
#kazoocon14
HTTP/HTTPS
Kazoo APIs are provided over HTTP/HTTPS
#kazoocon14
In most cases Kazoo APIs work just like a website!
#kazoocon14
What do the HTTP requests do?
#kazoocon14
Resources
Resources are just “Things”.
#kazoocon14
Collections
Collections are just a group of resources of the same type.
#kazoocon14
EntitiesEntities are a single instance of a resource.
#kazoocon14
IDs
We use IDs to identify entities.
#kazoocon14
But how do we tell the server what resources we want to
interact with?
#kazoocon14
Uniform Resource Identifiers (URIs)
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
#kazoocon14
URI – Uniform Resource Identifier
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
#kazoocon14
URI – Uniform Resource Identifier http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456
Base URL = http://test.2600hz.com:8000
/v1/
#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/
#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/
#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/
#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/
#kazoocon14
How do we tell the server what to do with the resource
we identified?
#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
#kazoocon14
Verbs for interacting with collections
GET - /v1/accounts/C1234/users/
PUT - /v1/accounts/C1234/users/ + data payload
#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
#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
#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
#kazoocon14
What is the payload?
#kazoocon14
Payload
A payload is the representation of the resource we requested.
#kazoocon14
Kazoo APIs mostly uses the JavaScript Object Notation (JSON) data format for most payloads
{ “key” : “value”}
#kazoocon14
Key value pairs
“key” : “value”
#kazoocon14
Key example:
“key” : “value”
#kazoocon14
Value examples
“key” : “value”
#kazoocon14
JSON Data Types:
“string_example” : “a string”,
“number_example” : 1,
“boolean_example” : true,
“null_example” : null,
“array_example” : [ “a string”, “a number” ],
“object_example” : { “some_key” : “some_value”, “other_key” : 1 }
#kazoocon14
JSON BASE OBJECT
{ “key” : “value”}
#kazoocon14
Complex nested JSON example:
{ “level_one_object” : { “level_two_object” : { “level3_key” : “level3_value”, “level3_array” : [ “level4_value” ] }, “level_two_array” : [ “level3_value” ] }}
#kazoocon14
In the API, we always have a “data” object which contains the payload.
{ “data” : { “parameters_for_resource” : “some value” } “metadata_stuff” : …}
#kazoocon14
Putting it all together.
#kazoocon14
#kazoocon14
#kazoocon14
#kazoocon14
#kazoocon14
To recap.
#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.
#kazoocon14
Ok, let’s play with the Kazoo APIs!!!
#kazoocon14
Tools for exploring Kazoo APIs
• Kazoo UI, Developer tools• Curl – Command Line Tool• Postman – Browser based.• SDKs (Software Development Kit)
#kazoocon14
Tools for exploring Kazoo APIs
• Kazoo UI, Developer tools http://kazooui.kazoocon.com
• Curl – Command Line Tool• Postman – Browser based.• SDKs (Software Development Kit)
#kazoocon14
Authentication TokensTemporary “Security tokens” used to authenticate clients.
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
How to get one:
#kazoocon14
Tools for exploring Kazoo APIs
• Kazoo UI, Developer tools• Curl – Command Line Tool• Postman – Browser based.• SDKs (Software Development Kit)
#kazoocon14
Tools for exploring Kazoo APIs
• Kazoo UI, Developer tools• Curl – Command Line Tool• Postman – Browser based.• SDKs (Software Development Kit)
#kazoocon14
Tools for exploring Kazoo APIs
• Kazoo UI, Developer tools• Curl – Command Line Tool• Postman – Browser based.• SDKs (Software Development Kit)
#kazoocon14
CreateNewAdminAccount
#kazoocon14
CreateNewAdminUser
#kazoocon14
PHP SDK example sign-up form.
#kazoocon14
Links
Github link for PHP SDK:https://github.com/2600hz/kazoo-php-sdk
Google Groups:https://groups.google.com/forum/#!forum/2600hz-devhttps://groups.google.com/forum/#!forum/2600hz-users
Sign-up page:http://userxxx.u.kazoocon.com/sign_up/gobblin/#ajax/signup.html
Thank You!
#kazoocon14