Join Keith Casey for an in-depth discussion in this video Authentication and authorization, part of Designing RESTful APIs.
- [Instructor] Now that we've covered your nouns and verbs and what rest is let's talk about some of the common API design patterns that you'll use to tie them all together. We'll start with authentication and authorization, which are affectionately known as authn and authz. First, we have to remember that they are different. Authentication is establishing who you are. You do this every time you use a website with a username and password. When I log into my banking website, I establish that I am Keith, and it allows me to continue.
But that's not where the process stops. Generally, once you establish who you are, it's important to verify what you're allowed to do, or your authorization. Most people confuse the two, and they design permission systems based on every user having one specific set of permissions. For example, when I log into my bank website, it only shows me my accounts. Those are the ones that I'm authorized to see. If I see your bank account, that's a huge security breach. The same applies in APIs. Many APIs have tiers of access based on the user's role, their group membership, regular versus admin users, payment or subscription level, and a variety of other things.
This authentication and authorization can be implemented in a variety of ways. Both APIs that are three main patterns that are the most common by far. First, we have an API key. This is a long string issued by the API provider and either a pennant to the URL or included as a header in the request. This is by far the simplest and easiest way to deal with from any programming language, framework, or even curo on the command line. There are two downsides we have to consider, though.
First, if we include this key in the URL, it's convenient, but it's going to be captured and logged by every cache, router, and device between us and the API itself. This is not secure. If we move the key to the headers, that's much better, but we're still stuck with the problem that this key can't be rotated easily if it's compromised. We may have to update all of our applications, which may require redeployment in a variety of different places. The second common approach is to role your own protocol.
Someone comes up with a handshake protocol, an encryption, they come up with a hashing mechanism, they combine them all together and they send them along. The benefit to this is, well, there are none. There are absolutely no benefits to doing this yourself. Do not do this under any circumstance, ever. Yes, even the one you're thinking of right now. The problem is that we think we're smart people and that we have this figured out. The problem is, that we don't. There are hundreds and even thousands of people who have struggled with, failed, succeeded, failed again, and come up with some solid solutions that work.
If you build your own encryption or security and it's compromised, I suggest you update your resume, because you will be looking for a new job. Further, think of the training. If you have your own custom scheme, you guarantee that your new team members, customers and partners have never seen it before. You'll have to train all of them on it before they can do something useful. And finally, remember that you won't have the tools other developers or existing libraries available. All of the things, all the resources you use to accelerate your own development simply don't exist.
You're stuck building everything yourself. It's like a mechanic who builds their own wrenches. It doesn't make sense. The final, and the most common of the API authentication approaches is OAuth. Well, that's not quite correct. OAuth is actually an authorization protocol. It doesn't define how you authenticate. Just that you must authentication with a trusted entity. The access token you get back describes or internally maps to a description of what actions you are and are not allowed to do. That's where the authorization comes in.
At this point, OAuth 2.0 is the recommended approach for APIs. It's not always well understood, but it's widely established and used by your favorite APIs. There's a massive ecosystem of tools, libraries, documentations, and even training options around it. Unfortunately, it's not always the easiest or the fastest. And in all seriousness, it's not something you want to build yourself. There are tons of commercial and opensource solutions out there, try those first. To be fair, I could spend quite a bit more time talking about this.
And I do, in a separate course. Check out the course catalog to find my session on OpenID connect and Oauth 2.0, and we can spend a couple of hours working on that specifically. Now that we've covered authentication and authorization, let's cover the most continuous topic of all in APIs, versioning.
- Approaches to adding an API
- Modeling tips
- Identifying activities and breaking them into steps
- Mapping activities to verbs and actions
- Creating and grouping API methods
- Validating your API
- HTTP headers and response codes
- Common design challenges
- Versioning best practices
- Hypermedia and documentation approaches