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!

1. PRESENTED BY:
Sean & Ricky
INTRODUCTION TO
KAZOO APIs

2. #kazoocon14
What is an API?

3. #kazoocon14
Application
Programming
Interface

4. #kazoocon14
An API as a bolt.

5. #kazoocon14
REST
Kazoo APIs are an example of a RESTFul web-service.

6. #kazoocon14
HTTP/HTTPS
Kazoo APIs are provided over HTTP/HTTPS

7. #kazoocon14
In most cases Kazoo APIs work just like a website!

8. #kazoocon14
What do the HTTP requests do?

9. #kazoocon14
Resources
Resources are just “Things”.

10. #kazoocon14
Collections
Collections are just a group of resources of the same
type.

11. #kazoocon14
Entities
Entities are a single instance of a
resource.

12. #kazoocon14
IDs
We use IDs to identify entities.

13. #kazoocon14
But how do we tell the server
what resources we want to
interact with?

14. #kazoocon14
Uniform Resource Identifiers (URIs)
http://test.2600hz.com:8000/v1/accounts/C1234/users/U3456

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

27. #kazoocon14
What is the payload?

28. #kazoocon14
Payload
A payload is the
representation of the resource
we requested.

29. Kazoo APIs mostly uses the JavaScript Object Notation (JSON) data
format for most payloads
#kazoocon14
{
“key” : “value”
}

30. #kazoocon14
Key value pairs
“key” : “value”

31. #kazoocon14
Key example:
“key” : “value”

32. #kazoocon14
Value examples
“key” : “value”

33. #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 }

34. #kazoocon14
JSON BASE OBJECT
{
“key” : “value”
}

35. #kazoocon14
Complex nested JSON example:
{
“level_one_object” : {
“level_two_object” : {
“level3_key” : “level3_value”,
“level3_array” : [
“level4_value”
]
},
“level_two_array” : [
“level3_value”
]
}
}

36. #kazoocon14
In the API, we always have a “data” object which
contains the payload.
{
“data” : {
“parameters_for_resource” : “some value”
}
“metadata_stuff” : …
}

37. #kazoocon14
Putting it all together.

38. #kazoocon14

39. #kazoocon14

40. #kazoocon14

41. #kazoocon14

42. #kazoocon14
To recap.

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.

44. #kazoocon14
Ok, let’s play with the Kazoo
APIs!!!

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)

51. #kazoocon14
CreateNewAdminAccount

52. #kazoocon14
CreateNewAdminUser

53. #kazoocon14
PHP SDK example sign-up form.

54. #kazoocon14
Links
Github link for PHP SDK:
https://github.com/2600hz/kazoo-php-sdk
Google Groups:
https://groups.google.com/forum/#!forum/2600hz-dev
https://groups.google.com/forum/#!forum/2600hz-users
Sign-up page:
http://userxxx.u.kazoocon.com/sign_up/gobblin/#ajax/sig
nup.html

55. Thank You!
#kazoocon14