0. Web technology to evolve
The flow of the times is ruthless…
“HTTPS”, “OpenID”, “OAuth”,,, “Basic technology”, which general users should understand properly about, is becoming more sophisticated and complicated every day.
In the speed of evolution of information and communication technology, even professionals who work for a company commonly known as an “IT start-up” do not have time to understand them all. “OAuth”, “a password-free collaboration technology” that is now being used by so many sites / applications for example, the outline is not yet deeply understood.
In this article, I will try to explain the outline of “the latest web technology” in a simple way so that even general business users can somehow understand it. Starting from “What is a server?”, to “What is OAuth?” …
“What’s it for?”
The reason behind it is that, the opportunity to explain more advanced cutting-edge technical terms has increased, since the “external system cooperation function” of our company Workflow product “Questetra BPM Suite” has been upgraded… (?!)
1. Two terms important for you to understand Web technology
What is a server? What is OAuth?
1-1. Referred as “Server”, because it serves services!
What is a server?
When you hear the word “Web server”, you might feel dizzy. When you hear the word “Beer server(*)”, you might feel happy.(* In Japan, Beer taps are referred to as Beer server)
But if you think carefully, it’s a “server” because it’s a machine for serving. There is no big difference between the two. Surely, there are not many opportunities to see a “Web server” (in real life), but there is nothing to be afraid of. It is only a “machine that does something on the Internet”.
What is important here, is the fact that it is based on “request” and “response” in the world of the Internet (≒ HTTP / HTTPS). Strangely, many people seem to have forgotten that. However, if you do not understand that, your comprehension of Web technology (the mechanism of the Web) will not improve. In this way, “the side to respond to requests” is the “server”. (And the requesting side is referred as “client”)
1-2. Is it called “Interface” because it is facing somebody?
UI, a term which many people may have heard sometime… Stands for ‘User Interface’.
In the case of “smartphone applications” (also “native applications”) like video games, an “interface” is displayed via a “smartphone application” itself which received the information from the server. Also, in the case of a system using a “general purpose software” (browser), a “Web server” itself transmits data after arranging the layout of information.
Anyway, UI is a mechanism for providing information to a USER (human), that machines close to humans present as a “layout of information”.
# When I heard from a sales representative explaining only the parts where a user can see, like saying “Our system sticks to UI, definitely this sophisticated UI …”, I personally tend to think that ‘Is the internal mechanism not sophisticated?’, or ‘I want the explanation about the entire system’s mechanism’. Yet, such a thing is unimportant.
Whereas, an API, is a “PROGRAM Interface”.
The partner of “UI” was the “USER”, but the partner of an “API” is the “PROGRAM”. That is, it refers to the information providing a mechanism against to a program (software). In this case, there is no need to make an information layout easy for a human being to understand. That part is not necessary. (* Application Programming Interface)
Now, what is important here are the facts that
・in addition to computers “providing information to people”,
・computers are also “providing information between them”.
In fact, a chain-like communication between “(1) smartphone (2) server (3) other server”, etc. is being carried out. And even when the human being (USER) is sleeping, such communications are taking place.
Even though it tends to be ignored, unless you are aware of the fact that information is provided between machines, your comprehension of Web technology (the mechanism of Web) will not improve.
2. “Request” and “Response”
Close your eyes and imagine,,, There are countless “requests” on the Internet… Recognizing the “presence of a server” (1-1) and the “interface of the server” (1-2),
2-1. Types of “Request”
First of all, I want to delve into the transmission, that is, the “request”…
A. Not handing over anything when transmitting request
B. Handing over something when transmitting request
First, there are two types of “requests”. (There really are more.)
Since it is hard to recognize, I would like you to imagine a beer server.
Imagine a “Beer server with only one tap” and a “Beer server like a vending machine”. You see, upon the same request, there are servers that require “money” and ones that don’t.
There are two methods “a. Simple request” and “b. Request with content” for “Requests” that are flying over the Internet.
a. postcard-like “request”
b. envelope/ parcel-like “request”
The difference between them is the presence or absence of “contents”. In the case of “a. Simple request”, only a so-called URL is enough. For example, if you write “http://www.questetra.com/blog/”, it means that you are asking to “Displaying a blog page”.
Experts call this method “GET method”. “Professionals” use expressions, such as “ah, that data is delivered by GET” or the like, they are talking about “a. Simple request”.
On the other hand, the “request with contents” cannot be done with just the URL. When answering the questionnaire form or to upload an image, you must hand over a “request” as “envelope” or “parcel”. This method is referred to as “POST method”.
Hmm. Wait a minute. The metaphor of “envelopes” and “parcels” may be even wrong somehow…
Yes, in the case of an “envelope”, only text information is contained, while in the case of a “parcel” it contains binary information such as photos and videos.
So, “Requests” are roughly classified into the following three types. (Oh no, I’m getting dizzy!)
a. Postcard⇒ “GET method”
b1.Envelope⇒ “POST method (application/x-www-form-urlencoded)”
b2.Parcel⇒ “POST method (multipart/form-data)”
2-2. Types of “Response”
So, what kind of “responses” are there?
It is not difficult to think about, that a “response” (reply) always has “contents”.
“Text/html”, “text/css”, “application/octet-stream”, “video/mpeg”…
You don’t have to know it all since there are so many types (I do not know them all either), but there are also “text type information” and “image type information”.
The important fact here is that a “Response” is very similar to a “Request”. In fact, both are referred to as “messages”. By the way, there is no “URL” or “method order” in an “envelope” or “parcel” “response” (it is mandatory for “requests” only).
2-3. “Request” to API and “Response” from API
Hold on a second…
They say, Web communications of these days are carried out between computers.
That’s right, the “content” that is popular among computers is “application/json”, now.
(The contents of) “Response” from the API is “application/json” or “application/soap+xml”.
As I already explained, it is hard to read for human beings. But, it is very easy to read for machines.
The important thing here is that not only in “response” but also in “request”, it is a fact that “communication formats hard to read by humans” are widely used in communication with APIs.
# Incidentally, since json and xml are texts, the downside is that it is difficult to put image type data.
3. Examples of API Request
Well, let’s take a look at examples of “API request” based on the explanation so far.
3-1. Case: Adding schedule to a calendar
Here, I write an example of a request. I use an API called quickAdd.
Request:
POST https://www.googleapis.com/calendar/{TeamCalendarID}/events/quickAdd
Content-Type: application/x-www-form-urlencoded
text=Meeting 2014-01-22If only one of you understand this, I would be satisfied for having written this article. In the request above, it says
“I send a request by an envelope (POST)” at the top and in the part of Content-Type, “Add a schedule (events) to the calendar {TeamCalendarID}” in the URL, “The content of the schedule is ‘Meeting 2014-01-22′” in the body.
And then, soon the response with content of “registration completed” is returned from the server in json format.
Response:
{
“kind”: “calendar#event”,
“status”: “confirmed”,
“created”: “2014-01-21T07:28:46.000Z”,
“updated”: “2014-01-21T07:28:46.357Z”,
}
3-2. Case: Posting a blog article
Request:
POST https://www.googleapis.com/blogger/v3/blogs/{TeamBlogId}/posts?isDraft=true
Content-Type: application/json
{
“content”: “Hello<br>Hello<br>Hello”
}In this request sample, it says;
“I send a request by an envelope (POST)” at the top, “Append an article to the blog {TeamBlogId}” in URL part, “The content of the article is ‘Hello<br> Hello<br> Hello<br>’” in the body
This is an example in which we are using json also for in the body. And json is also in the response:
{
“kind”: “blogger#post”,
“content”: “Hello<br> Hello<br> Hello<br>”,
...
}
4. The Request, allowed by Whom?
Now that you are able to understand the “Request to API” and “Response from API” concepts.
However, not everyone can make a request. That is, there is an authority issue. So, what is important here is the “authorization” technology. That is referred to as OAuth, which is now used in various services such as Facebook and Twitter.
OAuth communication between Web servers can only communicate with “authorized systems” by system users.
In the following, I will mention about knowledge which “System operators / Configurators” and “Business Process designers” should know. Not for “System users”. In other words, those who only use it as a daily user do not need to know the following contents.
By the way, the concept of “permission” (authorization) is essentially different from the concept of “giving ID and password” (authentication). For example, if it is a “permission”, you can cancel it later. But it is difficult to ask to forget “ID and password”.
4-1. Setting up OAuth 2.0 communication
In short, “OAuth communication setting” is “a setup for automatic transmission and reception”. The flow is roughly as follows:
However, it would be faster for you to learn about “authorization setting” by actually doing it in the setting screen. Even if I write the procedure etc. In detail, it is not easy to get it into your head. So, forgive me, but I recommend you to access the “Google Console” first, and to start from creating a new “Project”! ※ https://cloud.google.com/console/project
1) Setting up automatic connection reception (Google side)
1-1. Federation setting user to access “Google console”
1-2. Go to the [Credential] menu and create [CLIENT ID]
– “Callback URL” of Questetra is required
1-3. Acquire “Client ID” and “Client secret”
2) Setting up automatic transmittal (Questetra side)
2-1. Create Process Model (Business Process Definition)
2-2. Create a Date type Data Item and a String type Data Item
2-3. Generate a string to be automatically sent
2-4. Register the Credential in [OAuth 2.0 setting] of the automatic transmission icon
2-5. Set the transmission destination in the “Communication setting” of the automatic transmission icon
More details: Cloud-based Workflow and Google Calendar (OAuth 2.0 federation) (2014-01-27)
http://en.workflow-sample.net/2014/01/oauth2-google-calendar.html
4-2. Basic knowledge of OAuth 2.0 communication
Credential
Certificate for specific communication issued on the OAuth server side
Types of OAuth 2.0 server
A. API that provides only a connection permission (Access Token)
B. API that provides a mechanism for updating connection permission (Refresh Token) included
1. API that specification of permission range (Scope) is mandatory.
2. API that specification of permission range (Scope) is arbitrary.
Component of OAuth 2.0
a. OAuth 2.0 client
– a1. Program embedded in Web Application (Confidential client on Web server)
– a2. Program embedded in the Web client, etc (User-agent-based application)
– a3. Program embedded in local applications such as Android / iOS (Native application)
b. OAuth 2.0 authorization server (to issue access token: Authorization Server)
c. OAuth 2.0 resource server (to provide data, etc.: Resource Server)
OAuth 2.0 Terminology
[Consumer key] ID for identifying the client (client_id)
[Consumer secret] The secret key in pair of the client identification ID (client_secret).
[Authorize URL] Confirmation screen on which the end user gives permission to use the resource to the client
[Redirect URI] Endpoint that the client will receive an authorization code etc.
Specification of OAuth 2.0 communication [RFC6749,RFC6750] [RFC6749,RFC6750]
http://tools.ietf.org/html/rfc6749
http://tools.ietf.org/html/rfc6750
5. Summary
- There are types of request called POST / GET to send a “request” to the server.
- “Request” to the server may or may not have contents.
- “Response” from the server has various contents.
- Text communication called “json” seems to be prevalent in API communication between computers.
Although it was a very rough overview, first of all, if you have “system development knowledge” of this degree, it will be possible to set up automatic cooperation communication. The above knowledge does not require “programming knowledge”.
However, it is tough for system integrators (system construction) in this Cloud era.
After all, they must face “OAuth resources” around the world. In addition to so-called communication knowledge, they are required a wide range of knowledge, such as where and what kind of the “OAuth resource” are there, how much the use cost will be, or what measures should be taken if “OAuth resource” was unavailable.
P.S. Recommendation of Free trial
The cloud-based Workflow “Questetra BPM Suite” can be used for free if only a few people will use it! And, it has OAuth 2.0 client function as standard functionality.
There are still various functional restrictions, but I would like you to give it a try.
P.S.2 FAQ for Experts
The access token is sent in the HTML header. Currently (as of v9.8), it is not possible to send a request with “multi-level json data”. For File type data, the filename is sent. If you set to send multiple data with the same parameter name, it becomes an array.
