This is a comprehensive series of short, precise, and accurate unofficial definitions of terms you'll experience this week. It can only create a surface level understanding.
Memorizing strongly discouraged. Referencing strongly encouraged.
An Access Token, sometimes called a "User Token", is created when a user logs into an application using OAuth. It is unique on a per-user-per-application basis. An Access Token can be shared publicly without risk. Think of them as the "username" for OAuth's Authentication.
An Access Token Secret, sometimes called a "User Secret", is created when a user logs into an application using OAuth. Access Token Secrets are unique on a per-user-per-application basis. You should never share a users Access Token Secret, as they are the "password" of OAuth's Authentication.
Authentication is how an application identifies you. At the user level, this is often by using a username/password combination. At the application level, this is often using an API Key and a shared secret.
Not to be confused with Authorization.
Authorization is how an application decides what someone is allowed to do. For instance; you may be allowed to deposit money into any bank account; but you can only withdraw money from your own. Authorization is usually dependent on valid Authentication.
The Twitter API allows your application to work in two contexts: the application context and the user context.
- The Application context identifies which application is making each request using a Consumer Key and a Consumer Secret
- The User context identifies which user is making each request using an Access Token and Access Token Secret
These 4 pieces of data are used to create the Authorization header that is part of an OAuth request.
An API is a way to expose parts of a program so other programs may use it.
APIs can be built on the Web as Web Services or they can be programs running on your computer.
An example of an API for a program are browser plugins. Plugins such as Hey Girl and Mustachio Redux use the browsers api to change pictures as you browse the web.
The client/server model is a common approach to sharing data between many programs. This week, twitter's web service will act as the server; and the program you build will be the client.
The server is responsible for storing data and ensuring the client only interacts with the data it's allowed to, and the client is responsible for handling the user interactions.
A Consumer Key, sometimes called an API Key, is used to identify your application when sending requests to a web service that uses OAuth. Consumer keys are generated when you register your application with the web api. Consumer Keys may be shared publicly; as they are analogous to a username when using OAuth for authentication.
A Consumer secret, sometimes called an API Secret, is used to identify your application when sending requests to a web service that uses OAuth. Consumer secrets are generated when you register your application with the web api. You should not share consumer secrets publicly; as they are analogous to a password when using OAuth for authentication.
Data is a hard concept to explain. Think of it as the value of a variable. Take the following code:
name="Zee"
beard_length=9001
skills=[:programming, :typing, :sleeping, :grumping]The data contained in name is the string "Zee". The data contained in the
variable skills is an array of 4 symbols. Data can be transformed into
different formats through the process of
encoding
Data formats are how you can represent data to either a person or program. CSV's are a type of data format designed to represent spreadsheets. JSON is another common data format for transferring data between programs over the Internet. HTML is a data format for presenting data in a human readable way in a browser.
We're using the dotenv gem to store sensitive information like
your Twitter consumer secret. This lets us use the line
Dotenv.load ".env" to add the key-value pairs to the global ENV hash. Often
used with .gitignore to prevent storing sensitive data in your git
repository repository.
See https://github.com/codeunion/dotenv-example for a guide on how to use dotenv to manage sensitive information.
Encoding is the process of turning data from one form to another. I've encoded an important message: "Ogrammingpray isay awesomeay." Your brain has probably "decoded" this message into "Programming is awesome." Encoding allows you to put data into a format that other programs can read.
Encryption is a form of encoding data so it is only readable by parties who are allowed to read it. It's often used for HTTP requests that carry credit card or password data.
Gems are code that is written to be re-used within more than one ruby codebase.
A gem you use in your project is called a dependency.
It is a common practice to list every gem you're project uses in the projects
Gemfile. This lets a new team member run bundle install and begin using your
project.
The .gitignore file tells Git not to include a file in a given repository.
It's a list of files and patterns that match files to exclude when you run git add.
A protocol used to transmit data on the Web. It is client-server based and built on top of the Internet Protocol. HTTPS is an alternative protocol used to transfer data securely using encryption.
Reference How HTTP Works for a more detailed illustration.
Every HTTP Request and Response has metadata attached to it. This week, only a few headers are likely to be important:
- Authorization - Identifies the sender of the request to the web serice
- Content-Type - States the data format of the request or response body.
There are four main "verbs" used in web services:
- GET - Retrieves data from the service
- POST - Adds data to the service
- PUT - Replaces data in the service
- DELETE - Removes data from the service
Every HTTP Request uses one of these verbs in conjunction with a URL to change data in the web service.
The Internet is used to describe all of the different services like email, websites, chat, games, etc. that communicate over the Internet Protocol.
The Internet Protocol is a protocol that defines how computers on the Internet send packets of information. websites, chat, etc. that communicate over the Internet Protocol.
JSON is a very common data format used in web services. It is very human readable, and supported in many languages. The following is supermans hero information in a ruby hash and the JSON equivalent:
{
:alias => "Superman",
:name => "Clark Kent",
:years_active => 60,
:powers => ["flight", "xray_vision", "heat_vision", "invincibility"]
}now in JSON
{
"alias": "Superman",
"name": "Clark Kent",
"years_active": 60,
"powers": ["flight", "xray_vision", "heat_vision", "invincibility"]
}OAuth is a protocol built on top of http to allow client applications to access a users data without needing to store their password. You will use the authorization header to provide the twitter web-service with the appropriate user context.
For more details; check out our OAuth guide
Protocols define how computers communicate. There is a wide ecosystem of protocols, each with different purposes. They are often specified using a Request for Comment. There are many kinds of protocols with different purposes. SMTP, POP and IMAP are all for email; HTTP is for web pages; Jabber (or XMPP) is for chat, and many many more. Don't worry about learning the protocols details at the moment.
Query variables are used to pass data to the server in an HTTP
Request. They are part of a URL
that comes after the ?; and follow the format
name=value&other_name=other_value.
HTTP Responses are returned from the web service to the client who sent the request. Responses are composed of a status code, some headers, and a body that contains data.
HTTP requests are one half of the Request/Response Cycle. Requests are composed of a method, a URL, headers, and sometimes a body.
HTTP works by connecting the client and web service for a single transaction.
The client sends a request to the server for processing. Once the server finishes it creates a response and sends it back to the client.
For more information, read How HTTP Works
RFCs are public documents outlining a standard in the technology industry. While exhaustive and academic, they provide all the information necessary to implement a standard. They are often used for reference.
RFC 2616 exhaustively documents how to implement HTTP. Don't worry, it's only 147 pages!
A more readable one is RFC4180 which specifies how to format CSV files in a mere 7 pages.
Not all RFC's are computer focused, RFC 2119 is an RFC for people who write RFCs!
Status codes are part of the response that carries quite a bit of information. Status codes start with the numbers 1 to 5, and each have specific meaning:
- 1XX - Informational
- 2XX - Success
- 3XX - Redirection
- 4XX - Client Error
- 5XX - Server Error
The most common status codes are:
- 200 OK - Everything went great
- 404 Not Found - The URL you requested doesn't exist
- 401 Unauthorized - The Authorization header you included doesn't permit you to access the url you requested
A more comprehensive list may be found on wikipedia.
The Uniform Resource Locator, often called the web address, is a mainstay of the Internet. It's used to identify where a resource lives on the Internet in a human-and-robot readable fashion.
The Web is used to reference interconnected web sites served up over HTTP. Easily confused with the Internet
A web service (or web API is a program hosted on the web designed to be used by other programs. Using Yelps API you could write a lunch decider app that interacts with their search API and selects a single location based upon whatever criteria you like.
To use a web service, your program sends requests to a url and gets data back, often encoded in JSON.