APIs_ An Introduction.pptx

Editor's Notes

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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>.
9. 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.
10. 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.
11. 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>.
12. Next, we'll talk about authentication, which is how you obtain a secure token that allows you to access an API.
13. 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.
14. 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.
15. 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.
16. Now that we have learned about the different grant types, I'll show you how to create OAuth credentials in IDN.
17. Next, we'll discuss authorization. 
18. 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.
19. 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.
20. 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".
21. Now that we know more about scopes and user levels, let's apply those concepts to a user in IdentityNow.
22. 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.
23. 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.