A weather app does not observe weather data itself, and a map app does not create its own maps. It borrows functions published by other services through an API. In this lesson, you will examine the HTTP system that supports the Web in greater depth and learn about service integration using Web APIs and JSON. It is no exaggeration to say that modern information-system development is made up of “combinations of APIs.”
HTTP — Requests and Responses
Web browsers and Web servers communicate using a protocol called HTTP. The basic unit is an exchange in which the client sends a request and the server returns a response.
A request includes a method that expresses “what you want to do.” Representative methods are GET, which requests data, and POST, which sends data to a server, such as when submitting a form. Other methods include PUT for updating and DELETE for deleting.
A response includes a three-digit status code representing the result.
・200 (OK): Success
・404 (Not Found): The specified page or resource does not exist
・500 (Internal Server Error): An internal error on the server side
The first digit has meaning: 2xx＝success, 3xx＝transfer (redirect), 4xx＝client-side error, and 5xx＝server-side error.
Web APIs — Gateways for Programs
An API (Application Programming Interface) is a “gateway (connection specification)” that allows external programs to use the functions of software. In particular, something provided over the Internet using HTTP is called a Web API. Instead of a human viewing a Web page in a browser, a program accesses a URL and receives data.
REST is a widely used design style for Web APIs. In REST, the rules are standardized so that “resources are represented by URLs and operations are represented by HTTP methods.” For example, GET /users/5 means “retrieve the user information for ID 5,” and POST /users means “register a new user.”
JSON — A Common Language for Programs
The most widely used format for Web API response data is JSON. JSON is a lightweight text format that encloses “name-value pairs” in braces. It can be read by humans and handled by almost every programming language.
GET https://api.example.com/weather?city=tokyo, the following JSON is returned.{"city": "tokyo", "temp": 28, "weather": "Sunny", "rain_percent": 10}From this response, a program can extract four values: “city＝tokyo, temperature＝28℃, weather＝Sunny, probability of precipitation＝10%.” The “?city=tokyo” part of the URL is called a query parameter and tells the server the condition “which city’s data is wanted.” A custom app can be completed simply by displaying these values on the screen. The API provider handles both weather observation and forecasting.
Manners and Cautions When Using APIs
Many APIs require users to obtain an API key to identify themselves. An API key is like a password intended only for you, and must not be embedded in a program and made public. Also, sending a large number of requests in a short time places a burden on the service, so a request limit (rate limit) is normally established. Read the terms of use and follow the provider’s rules; this is basic etiquette for API users. Combining multiple APIs to create a new service is called a mashup and is a standard method in modern Web development.
- HTTP is an exchange of requests and responses. GET (retrieval) and POST (sending) are the basic methods.
- Status codes are 2xx success／4xx client-side errors (such as 404)／5xx server-side errors (such as 500).
- A Web API is a gateway through which programs use functions and data over HTTP. REST means “URLs represent resources, and methods represent operations.”
- JSON is a lightweight data format consisting of name-value pairs. It is the de facto standard for API responses.
- Keep API keys secret. Follow rate limits and terms of use.
Practice Problems
- What do status codes 404 and 500 mean, respectively, and which is a client-side problem and which is a server-side problem?
- Explain in Japanese the information that can be read from the JSON
{"name": "科学部", "members": 12, "active": true}. - Give two advantages of incorporating another company’s map API into your own app compared with creating all map functions yourself.
Answers・Explanations
- Answer: 404 means “the specified resource does not exist” and is a client-side problem (4xx). 500 means “an internal server error” and is a server-side problem (5xx).
Explanation: A mistyped URL often results in 404, while a defect in the server program often results in 500. The first digit indicates where the problem lies. - Answer: The data contains three pieces of information: the name is “Science Club,” the number of members is 12, and the club is active (active is true).
Explanation: JSON is a collection of “name”: value pairs. Values can include strings, numbers, and Boolean values (true/false). - Answer: (Examples) ① You do not have to perform the enormous task of maintaining and updating map data yourself, greatly reducing development time and costs. ② You can use high-quality, up-to-date functions provided by a specialized company, such as route searching.
Explanation: On the other hand, there is a dependency risk because you may be affected by changes in the provider’s specifications, price revisions, or the discontinuation of the service.