KazooCon 2014 - Introduction to Kazoo APIs!
Download as PPTX, PDF5 likes4,901 views
The document is a presentation on Kazoo APIs, outlining the basics of APIs, HTTP requests, and JSON payload structure. It explains the concepts of resources, collections, entities, and how to interact with them using HTTP methods alongside practical tools for API exploration. It also covers authentication mechanisms and provides useful links and tools for developers working with Kazoo APIs.
![#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 }](https://image.slidesharecdn.com/finalkazoointrotoapis-141014171441-conversion-gate02/85/KazooCon-2014-Introduction-to-Kazoo-APIs-33-320.jpg)
![#kazoocon14
Complex nested JSON example:
{
“level_one_object” : {
“level_two_object” : {
“level3_key” : “level3_value”,
“level3_array” : [
“level4_value”
]
},
“level_two_array” : [
“level3_value”
]
}
}](https://image.slidesharecdn.com/finalkazoointrotoapis-141014171441-conversion-gate02/85/KazooCon-2014-Introduction-to-Kazoo-APIs-35-320.jpg)
KazooCon 2014 - Introduction to Kazoo APIs!
- 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
- 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)
- 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
Editor's Notes
- #2: 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
- #4: 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.
- #5: 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.
- #6: Kazoo APIs are based on the Rest Architecture. The philosophy behind Kazoo APIs is “what would the web do?”
- #7: The protocol which is used to access the API is HTTP/HTTPS. Which means in most cases…
- #8: 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.
- #9: Requests are just the mechanism for client application to view and interact with specific resource on the server.
- #10: Like a device, an account, a phone number, a user. We handle resources in two ways in our API….
- #11: The first way is as COLLECTIONS. All accounts, All users under an account…
- #12: Individual account, individual user…
- #13: Every entity has an ID we can refer to it by.
- #15: 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.
- #16: 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.
- #17: The next link is the version. V1 just means version 1. This indicates the VERSION of the API we are interacting with.
- #18: NEXT IN OUR CHAIN is accounts This is an endpoint. An endpoint is a collection of one the type of resource.
- #19: IF WE APPEND AN ID AFTER THE ACCOUNT ENDPOINT WE ARE IDENTIFYING A SPECIFIC ACCOUNT ENTITY.
- #20: IF WE ADD USER TO THE CHAIN WE ARE IDENTIFYING a collection of the USERS IN THIS ACCOUNT.
- #21: IF we add a USER_ID to the chain we are identifying a specific user on this account.
- #23: 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.
- #24: 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.
- #25: 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.
- #26: 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
- #27: 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.
- #29: 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.
- #30: Json is an easily readable, widely supported format for storing data in nested structures.
- #31: MOST OF THE DATA IN JSON IS REPRESENTED AS KEY VALUE PAIRS
- #32: A KEY IS JUST A NAME for the parameter
- #33: VALUES CAN BE ANY OF THE AVAILABLE DATA TYPES.
- #34: Json lets you encode common datatypes that exist all in mainstream programming languages.
- #35: The envelope of a JSON object is contained inside a base object.
- #36: You can pretty much represent anything using JSON objects.
- #37: 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.
- #39: 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
- #40: 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.
- #41: 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.
- #42: 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…
- #44: 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.
- #47: 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
- #49: 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
- #50: 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
- #51: 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