Download to read offline
![JSON… The
Language of REST
7
© 2023 SailPoint Technologies, Inc. All rights reserved.
{
"info": {
"title": "Animal Collection",
"version": 3,
"dateCreated": "2013-15-02T03:02Z",
"isFinal": false
},
"animals": ["tiger", "dog", "bird”]
}
JavaScript Object
Notation (JSON)
REST APIs can accept many
data formats, but JSON is
the most popular.
Data Types
JSON supports strings,
numbers, booleans,
objects,
and arrays.
Objects
Objects contain
one or more unique keys
with values that contain
any of the supported data
types.
Arrays
Arrays can contain a list of
any JSON value type,
including additional arrays
and objects.](https://image.slidesharecdn.com/apisanintroduction-230928054650-5b49f4c4/75/APIs_-An-Introduction-pptx-7-2048.jpg)
![Query Parameters
https://api.carinfo.com/api/v1/makes?domestic=true&sort=name
? – start of query parameters
& - combine two or more query parameters
domestic=true – only return objects where
the “domestic” field is set to true
sort=name – sort the response objects by
the “name” field
“Give me all makes that are domestic and
sort the results by name.”
10
© 2023 SailPoint Technologies, Inc. All rights reserved.
{
"results": [
{
"name": "Chevrolet",
"domestic": true
},
{
"name": "Dodge",
"domestic": true
},
{
"name": "Ford",
"domestic": true
}
]
}](https://image.slidesharecdn.com/apisanintroduction-230928054650-5b49f4c4/75/APIs_-An-Introduction-pptx-10-2048.jpg)
APIs_ An Introduction.pptx
- 1. </title> </title> APIs: An Introduction Colin McKibben LeadDeveloper Advocate SailPoint
- 2. Agenda 2 © 2023 SailPointTechnologies, Inc. All rights reserved. • Overview of REST • Authentication • Authorization • Understanding OpenAPI Specifications
- 3. REpresentational State Transfer Amethod of transmitting and receiving data over HTTP, following many of the conventions defined by the HTTP protocol. 3 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 4. URLs Represent Endpoints https://api.carinfo.com/api/v1/makes/ford 4 ©2023 SailPoint Technologies, Inc. All rights reserved. host collection basepath resource
- 5. Collection Hierarchies https://api.carinfo.com/api/v1/makes/ford/models/fusion/years/2011 5 © 2023SailPoint Technologies, Inc. All rights reserved. host collections basepath resources
- 6. Identifying Resources https://api.carinfo.com/api/v1/makes/2c9180835d2e5168015d32f890ca1581 6 © 2023SailPoint Technologies, Inc. All rights reserved. host basepath collections resource UID (Unique Identifier)
- 7. JSON… The Language ofREST 7 © 2023 SailPoint Technologies, Inc. All rights reserved. { "info": { "title": "Animal Collection", "version": 3, "dateCreated": "2013-15-02T03:02Z", "isFinal": false }, "animals": ["tiger", "dog", "bird”] } JavaScript Object Notation (JSON) REST APIs can accept many data formats, but JSON is the most popular. Data Types JSON supports strings, numbers, booleans, objects, and arrays. Objects Objects contain one or more unique keys with values that contain any of the supported data types. Arrays Arrays can contain a list of any JSON value type, including additional arrays and objects.
- 8. HTTP Verbs RepresentActions Create a new resource or execute an action: POST /avengers Data = { "callsign": "Iron Man", "relationshipWithCap": "good" } POST /avengers/iron-man/activate-thrusters Get one or more resources GET /avengers GET /avengers/iron-man Update a resource in its entirety PUT /avengers/iron-man Data = { "callsign": "Iron Man", "relationshipWithCap": "civil war" } Partially update a resource PATCH /avengers/iron-man Data = { "relationshipWithCap": "good"} Delete a resource DELETE /avengers/iron-man 8 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 9. HTTP Headers Headers aremetadata about the request and the response Common headers: • Authorization - Add an authentication token to the request (ex. "Authorization: Bearer <token>"). • Content-Type - The format of the request payload (ex. "Content-Type: application/json") • Accept - Tells the server how to format the response data (ex. "Accept: application/json") Headers can be used to control how data is sent to and processed by the server. • Accept-Encoding: gzip tells the server to compress the response data to save bandwidth. • Accept: text/plain tells the server to return plaintext data rather than a structured format like JSON or XML. Headers can also be used to learn more about the response data and take additional actions after a request has completed. • Count: 81 means there are 81 records returned in the response. • Deprecated: true means the endpoint is deprecated. Check the API spec to see what headers are supported. 9 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 10. Query Parameters https://api.carinfo.com/api/v1/makes?domestic=true&sort=name ? –start of query parameters & - combine two or more query parameters domestic=true – only return objects where the “domestic” field is set to true sort=name – sort the response objects by the “name” field “Give me all makes that are domestic and sort the results by name.” 10 © 2023 SailPoint Technologies, Inc. All rights reserved. { "results": [ { "name": "Chevrolet", "domestic": true }, { "name": "Dodge", "domestic": true }, { "name": "Ford", "domestic": true } ] }
- 11. Success Your request wassuccessfully executed • 200 = Successful request • 201 = Resource was created • 204 = No Response data 11 © 2023 SailPoint Technologies, Inc. All rights reserved. Response Codes Client Error Something you provided in your request was invalid. • 400 = Bad request • 401 = Unauthorized • 404 = Not found Server Error The server was unable to process the request. • 500 = General server error • 503 = Service unavailable
- 12. Authentication 12 © 2023 SailPointTechnologies, Inc. All rights reserved.
- 13. Create an APIkey or credentials API keys or credentials can't be directly used to authenticate API requests. They are long lived, and provide a means for you to create access tokens that can be used to authenticate requests. 13 © 2023 SailPoint Technologies, Inc. All rights reserved. Authentication Process Request an access token Access tokens are short lived, and can expire within minutes or hours. An expired token typically results in a 401 Unauthorized. If you receive this error, you likely need to generate a new access token. Use the access token to authenticate requests The access token is used in the Authorization header to authenticate requests.
- 14. Demonstration Creating a PersonalAccess Token 14 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 15. OAuth2 Grant Types AuthorizationCode • Requires the user to authenticate and authorize the application to act on their behalf • This is common for web apps where you need to sign in to allow the web app to fetch your data Refresh Token • Gives an application the ability to create new access tokens without requiring the user to authenticate as frequently • Refresh tokens can be used as many times as needed until they expire Client Credentials • Used to generate an access token outside the context of a user • Does not require the user to authenticate, but often doesn't have the same level of permissions as a user 15 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 16. Demonstration Creating OAuth2 Credentials 16 ©2023 SailPoint Technologies, Inc. All rights reserved.
- 17. Authorization 17 © 2023 SailPointTechnologies, Inc. All rights reserved.
- 18. Authentication vs Authorization Authentication:Verifying that you are who you say you are. Authorization: Verifying that you are allowed access. 18 © 2023 SailPoint Technologies, Inc. All rights reserved. Authentication Authorization Access to API
- 19. Scopes 19 © 2023 SailPointTechnologies, Inc. All rights reserved. • A scope grants access to one or more endpoints in an API. • API tokens can have one or more scopes, depending on the access it needs. • Scopes are a security feature that limits the breadth of access a token has. This can prevent legitimate users from accidentally accessing or modifying sensitive data. It can also limit the attack vector of a compromised token. Car Data API Get all cars Delete cars Get all cars Create and Update cars Token 1 is for an admin who needs to manage all car data, so it needs the following scopes: • Create and update cars • Delete cars • Get all cars Token 2 is for a small website that specializes in the history of cars. It only needs the following scope: • Get All Cars
- 20. IdentityNow User Levels 20 © 2023SailPoint Technologies, Inc. All rights reserved. • Some APIs implement custom authorization mechanisms. IDN implements both scopes and user levels. • User levels are sets of permissions within IdentityNow that administrators can grant to users. • User levels cover a broader range of access than scopes. They should be used in tandem to refine the access of each API user. IdentityNow API Report Admin User Level Admin User Level Scope Scope Scope
- 21. Demonstration Setting a UserLevel and Scopes 21 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 22. Demonstration How to ReadOpenAPI Documentation 22 © 2023 SailPoint Technologies, Inc. All rights reserved.
- 23. 23 © 2023 SailPointTechnologies, Inc. All rights reserved. Thank you!
Editor's Notes
- #2 Welcome to the first session of Developer Days! My name is Colin McKibben, and I am the lead developer advocate for SailPoint. This first session is all about the basics and is geared towards those who aren't familiar with REST APIs. This session will help provide a solid foundation of understanding that will be helpful for many of the sessions that are to follow. For those of you who are comfortable using REST APIs, I encourage you to stick around; you might learn something new.
- #3 In this session, I'll start with a general overview of REST and how requests to a REST API are created. Then I'll discuss authentication and authorization, with a demonstration of how to do both in IdentityNow. Finally, I'll help you make sense of an OpenAPI specification; how to read it, how to find the information you're looking for, and how to use it to craft API requests.
- #4 REST stands for Representational State Transfer, which is a fancy way of saying "data that is transferred over the HTTP protocol". Rather than creating an entirely new protocol, REST reuses many of the conventions of HTTP, which makes it easier for web developers to understand.
- #5 An endpoint is a specific URL that points to a resource or a collection of resources. When combined with an HTTP verb, like GET or POST, endpoints allow you to interact with the data they point to. The hostname represents the server that is hosting the API. Typically, this is a similar hostname to the company that owns the service. The basepath is a common URL path that is reused across endpoints. It is often used to specify a version of the API. The collection is a grouping of one or more resources. You can think of collections as folders on your computer. A folder is a collection of documents (or resources). Finally, the resource is a specific piece of data that you want to access.
- #6 Collections can have sub collections that allow for data hierarchies. If we take our computer folder example again, a folder can have sub folders that contain more specific data. In this example, the sub collections get more specific until we have the exact year, make, and model of car that we are interested in. Collections allow REST APIs to model data into hierarchies that are exposed directly in the URL, as opposed to having to craft specialized queries. This makes REST APIs easier to understand from the start without having to learn and explore with a query language.
- #7 REST APIs in the wild typically don't use human friendly names for resources. Instead, they opt for unique identifiers. While this makes it harder for humans to understand just by looking at the URL, there are many advantages for implementors of the service, such as guaranteed uniqueness, URL friendly identifiers, and security improvements.
- #8 REST APIs most commonly use JSON as the language for communicating between client and server. JSON stands for JavaScript Object Notation, and its simplicity, flexibility, and ubiquity make it a popular choice for web services. JSON supports basic data types that can model virtually any data it comes across. Strings model text, like names or descriptions; numbers model integers and decimals; and booleans model true/false values. Objects provide structure to data, giving a name to related key/value pairs and making it easier to find data within a JSON document. Objects can be nested within each other to create infinitely complex objects. Finally, arrays represent lists of values, where each item in the list is of the same type. This can be a list of strings, numbers, booleans, objects, or even additional arrays.
- #9 The HTTP protocol specifies five common verbs that are frequently used in REST services. Every endpoint specifies one or more verbs as a means of interacting with the data it points to. Typically, the HTTP verbs are used in the following scenarios: <cover the examples in the slide>.
- #10 Headers are another HTTP convention that provide metadata about the request and the response. Most REST services will stick with the standard HTTP headers, like Authorization, Content-Type, and Accept. There are other headers that aren't as well known, and anyone can create their own headers. Often times, each REST service that you interact with will support additional headers that allow you to further control how the data is processed by the server, or allow the server to provide additional context about the data it is giving you. For example, you could ask the server to send back a special header with the count of the number of records returned, rather than having to calculate it yourself, or the server could respond with a "Deprecated" header to inform users that a particular endpoint is going to be retired.
- #11 Query parameters are a way to explicitly control how data is processed and returned directly. They are defined in the URL, rather than as headers, making them more explicit. Typically, query parameters are supported on collection endpoints, which are endpoints that will return one or more resources. These query parameters will include common functionality like filters, sorters, and pagination controls. However, they can also be used to control other aspects of the request, such as enabling a special processing flag. Query parameters can be grouped together to form a complex query, such as in the example above. Query parameters are often very unique to each REST service, so it is important to read the API specification for each service to understand what is available.
- #12 Response codes are heavily borrowed from HTTP status codes, and they signal to the client if the request was a success or a failure. If you've ever visited a website page that no longer exists, you may have seen a 404 Not Found. That is an example of a response code. Codes that start with a 2 are considered a success, codes that start with a 4 are considered a client error, and codes that start with a 5 are considered a server error. Since response codes heavily rely on HTTP status codes, there are some common response codes that you will likely see across most REST services that you use. <cover the different codes in the slide>.
- #13 Next, we'll talk about authentication, which is how you obtain a secure token that allows you to access an API.
- #14 Most REST APIs use the OAuth2 authentication standard, but some may use less popular authentication mechanisms, like basic auth. Always check your API service's authentication guide to learn how to authenticate. In the case of IdentityNow, OAauth2 is the mechanism that we use. The authentication process for an OAuth2 API starts with creating API credentials. This is typically in the form of a client ID and client Secret, which is kind of like a username and password. These credentials aren't used to authenticate directly with an endpoint. Instead, you use these credentials to invoke a special authentication endpoint that will return an access token. Access tokens are short lived, usually lasting less than 24 hours. They are supplied in the Authorization header of an API request to authenticate the request. If the token is expired, you'll typically see a 401 response code, which means you need to generate a new access token to continue.
- #15 Personal access tokens are easy to create, and they are ideal for use in automated scripts where you don't want to have to log in periodically. Let's see how we can create our own personal access token in IdentityNow.
- #16 OAuth2 supports three main grant type. A grant type indicates how an access token will be created, and with what permissions or user context it will be given. The authorization code grant type is typically used in web apps where you want users of your app to login with their own username and password in exchange for an access token they can use to invoke APIs. This grant type isn't typically used for automated scripts, because it requires a login prompt and human interaction. The refresh token grant type is often used in conjunction with the authorization code to allow a given access token to be refreshed without requiring the user to login again. For example, if you create a web app that uses authorization code, the default token expiration may be 8 hours. This means users of your app will have to login every 8 hours to continue using the app. You could add the refresh token grant type and set a different expiration, which would allow users of your app to use it longer before having to login again. The last most common grant type is client credentials. In most cases, client credentials are used when you don't want to have a user repeatedly login, like in automated scripts. The downside is that there is no user context associated with a token produced by this grant type. In IDN, this is problematic because many of our APIs require some variation of an admin user. In the case of IDN, the personal access token that I mentioned before is a special kind of client credentials grant type that associates the token with the user that created the credentials, thereby eliminating the problem of no user context.
- #17 Now that we have learned about the different grant types, I'll show you how to create OAuth credentials in IDN.
- #18 Next, we'll discuss authorization.
- #19 Authentication is the act of verifying a user's identity. Authorization is the act of verifying that a user is allowed to access a given endpoint. When combined, these two concepts greatly enhance the security of APIs.
- #20 Scopes are a common form of authorization control for APIs. The API provider will create many scopes, with each scope providing access to a small set of APIs. Each API token can be assigned one or more scopes, which determine what endpoints the token is allowed to access. By assigning scopes to a token, API users can ensure their applications have the least level of privilege necessary to perform their intended functions. Least level of privilege is an important security concept that helps to reduce the severity of compromised credentials while providing safeguards for developers so they don't access or modify data they shouldn't have access to in the first place. In this example, the car data API provides three scopes, with each scope granting access to certain endpoints within the API. The first user is an admin of the car data database, and needs a token that can create, update, delete, and get all cars. This user's token is assigned the green scopes, which allows them to perform their role. The second user is the owner of a small website that specializes in the history of cars. This user shouldn't be able to modify any data, only get car data so it can be displayed on the website. This user's token is given the "Get all cars" scope, which allows the token to only get car data and not perform any other action. In the event that user two's token is stolen, the token can only be used to fetch car data and not perform any destructive actions.
- #21 IdentityNow provides another form of authorization, called user levels. User levels are unique to identity now, and they provide broad access to SailPoint APIs based on common user roles. User levels must be used with scopes to refine the access of an API token. The most powerful user level is the "Admin", which is allowed to access any API endpoint. The most restricted user level is the "User", which can perform a few basic actions like requesting access. Scopes can only be used to further refine the access that a user level is given, they can't be used to grant access outside of the bounds of a user level. For example, a "Report Admin" user level is allowed to access APIs pertaining to search and auditing. Scopes can be applied to this user to further limit that API access to just search, if necessary. However, scopes cannot be used to grant the "Report Admin" the ability to create or delete sources, since that is outside the bounds of the "Report Admin".
- #22 Now that we know more about scopes and user levels, let's apply those concepts to a user in IdentityNow.
- #23 OpenAPI is a standard for describing REST APIs. It is important to be able to read and understand OpenAPI documentation so that you can find the APIs you need as well as understand how they work.
- #24 This concludes the introduction to APIs. For those of you who are new to APIs, I hope you now have a better understanding of what REST APIs are and how to use them. And for those of you who are veterans, I hope you were able to learn something new from the information presented. Thank you all for attending, and I will see you in the next presentation.