KazooCon 2014 - Introduction to Kazoo APIs!

transcript

PRESENTED BY:

INTRODUCTION TO KAZOO APIs

Sean & Ricky

#kazoocon14

What is an API?

#kazoocon14

ApplicationProgrammingInterface

#kazoocon14

An API as a bolt.

#kazoocon14

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

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

#kazoocon14

/v1/accounts/

#kazoocon14

/v1/accounts/

/v1/accounts/C1234/

#kazoocon14

/v1/accounts/

/v1/accounts/C1234/

/v1/accounts/C1234/users/

#kazoocon14

/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:

#kazoocon14

Value examples

#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

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

• 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

CreateNewAdminAccount

#kazoocon14

CreateNewAdminUser

#kazoocon14

PHP SDK example sign-up form.

#kazoocon14

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

KazooCon 2014 - Introduction to Kazoo APIs!

Technology