diff --git a/ruby_on_rails/apis/working_with_external_apis.md b/ruby_on_rails/apis/working_with_external_apis.md index 6914b2a4292..d4246c40c9b 100644 --- a/ruby_on_rails/apis/working_with_external_apis.md +++ b/ruby_on_rails/apis/working_with_external_apis.md @@ -6,7 +6,7 @@ Most popular services offer APIs so developers can interface with them (they lov If you go to the documentation for an API, it can sometimes be a bit overwhelming because much of the material sort of assumes that you know what you're doing, but some are definitely better than others. There are also elements that are common across almost all of them. The more you work with APIs (and get the hang of the authentication flow), the easier they get. You'll be making mashups in no time. -This lesson will cover some general steps that are common across APIs and will do high level overviews of some of the methods for authenticating with APIs like Omniauth. Try to gain as much conceptual understanding as you can here and use the documentation each gem or API provides to help with the implementation. If you find great free learning resources that explain APIs, you can [suggest them via a GitHub issue in our curriculum repo](https://github.com/TheOdinProject/curriculum/issues/new/choose)! +This lesson will cover some general steps that are common across APIs and will do high level overviews of some of the methods for authenticating with APIs like Omniauth. Try to gain as much conceptual understanding as you can here and use the documentation each gem or API provides to help with the implementation. If you find great free learning resources that explain APIs, you can [suggest resources via a GitHub issue in our curriculum repo](https://github.com/TheOdinProject/curriculum/issues/new/choose)! ### Lesson overview @@ -32,9 +32,9 @@ You'll typically also get a "secret key" or similarly named code. Whereas the A Most APIs require a different type of "security clearance" for different requests: 1. You can usually make innocuous requests like asking for posts from X's (formerly known as Twitter) API with straightforward and unauthenticated GET requests. You can make these from any command line or a browser tool like [Chrome's Rest Client](http://getpostman.com). These types of API requests are usually severely rate limited to incentivize you to sign up. -2. The next layer is making requests that include your API key. These are still usually fairly innocuous things (like getting public data) and limited by the API's pricing tiers. -3. More sensitive requests like asking for specific user data or submitting/modifying/deleting data will likely require you to use an authentication process involving your secret token. We'll cover the basics of this in the project. Rates for these requests are subject to the API pricing tiers. -4. Oftentimes, you actually want to make requests on behalf of a user. For instance, showing a user a dashboard of all their posts and Facebook posts together would require asking X for that user's posts and Facebook for that user's posts. This can involve a LOT of requests over a large user base, but luckily you're actually able to make them on the user's behalf by asking for the user's permission. We'll cover this as well later, but basically you send the user to the API provider's site to sign in, then the API provider will give you a user-specific token to use when making requests on their behalf in the future. Rates for this are usually more advantageous because they are covered in a per-user bucket. We typically use the OAuth protocol for this, as described below. +1. The next layer is making requests that include your API key. These are still usually fairly innocuous things (like getting public data) and limited by the API's pricing tiers. +1. More sensitive requests like asking for specific user data or submitting/modifying/deleting data will likely require you to use an authentication process involving your secret token. We'll cover the basics of this in the project. Rates for these requests are subject to the API pricing tiers. +1. Oftentimes, you actually want to make requests on behalf of a user. For instance, showing a user a dashboard of all their posts and Facebook posts together would require asking X for that user's posts and Facebook for that user's posts. This can involve a LOT of requests over a large user base, but luckily you're actually able to make them on the user's behalf by asking for the user's permission. We'll cover this as well later, but basically you send the user to the API provider's site to sign in, then the API provider will give you a user-specific token to use when making requests on their behalf in the future. Rates for this are usually more advantageous because they are covered in a per-user bucket. We typically use the OAuth protocol for this, as described below. ### Versions @@ -77,15 +77,15 @@ OAuth 2.0 is actually pretty complicated, so we'll just cover the basic process. Basically (still using Facebook as an example): 1. User tries to access a page on your app and you ask the user to login -2. User chooses the "Login With Facebook" option -3. User is redirected to a Facebook page asking them to review the permissions you are asking for and telling them to sign in. The URI will contain parameters that tell Facebook who your application is and possibly which URI they should submit their response to (or maybe you specified this as a part of your API registration process with them). -4. User decides you seem like a fun application so they'll allow you to see their email address and post to their timeline. User signs in to their Facebook account. Facebook creates an authorization code and sends it back to your application's callback URI. -5. The user waits while your application takes that authorization code and uses it to ask Facebook for the real good stuff. Facebook makes sure your application is the same one the user authorized, then POSTs back to you a unique authentication token for the user (which likely expires in 90 days) and any data you asked for up front (like email address). -5. You store the user's unique token in your database and use it, along with your application key(s), to make any subsequent requests on the user's behalf. +1. User chooses the "Login With Facebook" option +1. User is redirected to a Facebook page asking them to review the permissions you are asking for and telling them to sign in. The URI will contain parameters that tell Facebook who your application is and possibly which URI they should submit their response to (or maybe you specified this as a part of your API registration process with them). +1. User decides you seem like a fun application so they'll allow you to see their email address and post to their timeline. User signs in to their Facebook account. Facebook creates an authorization code and sends it back to your application's callback URI. +1. The user waits while your application takes that authorization code and uses it to ask Facebook for the real good stuff. Facebook makes sure your application is the same one the user authorized, then POSTs back to you a unique authentication token for the user (which likely expires in 90 days) and any data you asked for up front (like email address). +1. You store the user's unique token in your database and use it, along with your application key(s), to make any subsequent requests on the user's behalf. See this brief [overview of OAuth 2.0](http://tutorials.jenkov.com/oauth2/overview.html). Then check out this [more substantive explanation of OAuth 2.0 from tutsplus.com](https://code.tutsplus.com/articles/oauth-20-the-good-the-bad-the-ugly--net-33216). -#### Implementing OAuth 2.0 in Rails -- Use OmniAuth! +#### Implementing OAuth 2.0 in Rails -- Use OmniAuth This sounds horribly complicated! Someone must have made a gem for it... @@ -95,33 +95,36 @@ Using Omniauth is much easier to learn by doing than reading a bunch of bullet p ### SDKs -In addition to or instead of API access, many companies provide SDKs (software development kits). Usually these are Javascript libraries that contain all the code necessary to access their API. This can be useful because you're then able to access the API with Javascript methods instead of doing backflips on your own backend. It comes with the downside, however, of expanding your code base and forcing you to use their conventions for everything. +In addition to or instead of API access, many companies provide SDKs (software development kits). Usually these are JavaScript libraries that contain all the code necessary to access their API. This can be useful because you're then able to access the API with JavaScript methods instead of doing backflips on your own backend. It comes with the downside, however, of expanding your code base and forcing you to use their conventions for everything. We won't cover SDKs explicitly in this course but they should be well within reach to pick up by reading the documentation. ### Assignment