Article that can be a human resource who understands and masters the mechanism of API (with Python code)
Introduction
I'm studying programming and what is API? Have you ever felt that?
** "What can you do with the API in the first place?" ** "How do you use this?"
To solve these problems, it is good to understand ** the mechanism common to all APIs **. I'll show you the specific Python code, so by the time you finish reading, you should be familiar with how to use the API.
- This article deals only with "Web API". * For those who want to know the difference between API and WebAPI here
The chapter structure is as follows.
--What is API (merits of using API) --Understanding the API --Example of API service --Python code sample
※※ Since various information is also posted on SNS, if you feel that it is okay to read the article I would be grateful if you could follow Twitter account "Saku731". ※※
What is API (merits of using API)
API is an abbreviation for "** A ** pplication ** P ** rogramming ** I ** nterface". The literal translation is as follows.
--Application --Using Programming --Connect (Interface)
- Application means "Web service" and "system".
Going a little deeper, the biggest advantage that APIs are needed is "** Borrow useful functions created by other people to the Web service you created **" I think this is all.
In other words, you don't have to work hard to develop from scratch. For example, when developing an EC site, which one would you choose?
--Create your own ** credit card payment function ** --Use the ** credit card payment API ** provided by the credit card company
In this way, the option ** "Do not make it yourself" ** is the greatest merit of the API.
Understand the API
Now that you know the benefits of the API, let's understand how it works. There are three main types of knowledge required.
―― 1) How the Web works ―― 2) HTTP request ―― 3) HTTP response
1) How the Web works
The Internet, which I casually use, is made possible thanks to the Web. The Web is a "** mechanism for sending all kinds of data such as texts and images on the Internet **".
So, of course, you need to understand the Web to borrow a Web service created by another person using the API. To understand the Web, let's hold down the following three.
- HTTP（Hyper Text Transfer Protocol） --URL (to be exact, URI) --Hypertext (HTML, etc.)
It is like this when organized in sentences.
What is the Web? "According to the communication promise of HTTP" "To and from the location (server) specified by the URL" A mechanism for "exchanging hypertext (information)".
I have to read many books to understand the Web in detail, It is enough to understand that it is "** technology for exchanging information with the server specified by URL **".
The API is a mechanism that makes it easy to exchange information between ** your own web service ** and ** web service (server) created by another person ** using this web technology.
And, in order to use the API concretely, it is necessary to use HTTP (communication convention) adopted by the Web. There are two types, "Send information to the other party ** HTTP request **" and "Receive information from the other party ** HTTP response **", so let's understand them later.
2) HTTP request
The first is an HTTP request that sends data from you to the other party. It is a process to send a request such as "Please let me use the function" ** to a Web service created by another person via API.
The API usage seems to be different for each Web service, but there is a common foundation. The following information should be prepared in common when using any API.
--Information for connecting to a Web service (obtained when registering the service) --API endpoint (URL to connect to the service) --API key (password required for connection) --Information to be sent to the Web service (can be confirmed in the API specifications) --Method (mainly POST or GET) --Query parameters (specify details such as API / service type to use) --Header (Enter authentication information such as data type and API key * Specify by POST method) --Body (Enter the information you want to send and receive with the API. * Specify with the POST method)
These ** major items are common to all APIs , but there are differences in the details. Check the required contents in the " API specifications **" published by each service.
- Until you get used to it, it is best to read the service usage procedure posted on Qiita.
If you use an API that can get the weather in each area, the information will be organized in this way. You don't have to be aware of it at first because it is written in the API specification whether to use POST or GET.
- If you want to know the difference in detail, please refer to [here].
In addition to POST and GET, there are methods called PUT and DELETE. It is roughly explained as follows.
--GET: Get data --POST: Create new data --PUT: Update the data --DELETE: Delete data
Weather forecast API (for POST method)
--Information for connecting to a web service --API endpoint: https: /world_weather.com/api * This is a fictitious URL. --API key: aaabbbccc --Information to send to the web service --Method: POST --Query parameter: service = Waityer (specify the service to use) --Header: application / json (data type) --Body: date = today, area = Tokyo (Enter the information you want to send and receive)
The sample program is as follows.
- Since it is an API that does not exist, an error will occur even if it is executed.
#Library import
import requests
#Information for connecting to the API
API_Endpoint = https:/world_weather.com/api
API_Key = aaabbbccc
#Information to send to the API
headers = {'Content-Type': 'application/json', 'key':API_Key}
body = {date='today', area=Tokyo}
#Executing API connection
result = requests.post(API_Endpoint, data=json.dumps(body), headers=headers)
Weather forecast API (for GET method)
--Information for connecting to a web service --API endpoint: https: /world_weather.com/api --API key: aaabbbccc --Information to send to the web service --Method: GET --Query parameters: service = Wednesday, date = today, area = Tokyo (In the GET method, all are stored in the query parameters)
The GET method is generally written as follows, although it depends on the service.
** ① Principle: Include all information in the endpoint (URL) **
#Library import
import requests
#Information for connecting to the API ("?"Behind"&”To connect the conditions)
API_Endpoint = https:/world_weather.com/api?Key=aaabbbccc&date='today'&area='Tokyo'
#Executing API connection
result = requests.get(API_Endpoint)
** ② requests module function: Separate information like POST **
This description method is similar to POST. On the back side, the data is sent in the same form as "(1) Principle", so the result is the same.
#Library import
import requests
#Information for connecting to the API
API_Endpoint = https:/world_weather.com/api
API_Key = aaabbbccc
#Information to send to the API
headers = {'key':API_Key}
params = {date='today', area=Tokyo}
#Executing API connection
result = requests.get(API_Endpoint, headers=headers, params=params)
3) HTTP response
When you send an HTTP request to a web service via the API, you will receive a "reply" called ** HTTP Response **. By displaying this "Reply" on your own Web service, you can save yourself the trouble of developing from scratch.
For example, "** Request **: Please tell me the weather. Today, Japan, Tokyo ”
"** Response **: Sunny then cloudy"
API service example
Now that you have an overview of the API, let's use a free API service that you can actually use.
Service overview of API to be used
Try using the Livedoor weather information service ** Weather Hacks **. You can get the weather forecast of 142 places all over Japan for free until "Today, tomorrow, the day after tomorrow".
http://weather.livedoor.com/weather_hacks/webservice
Take a look at the API specifications
Click the link above to see the API specification. The number of items and names vary depending on the service, but the order to check is as follows.
- What is the API endpoint?
- How to get API Key?
- POST or GET?
- What are the query parameters?
- What information should I send in the header body?
Let's organize them in order. This time it's a free service, so it's very simple.
- ** What is the API endpoint? ** ** http://weather.livedoor.com/forecast/webservice/json/v1
- Endpoints may be listed with names such as URL / URI.
-
** How to get API Key? ** ** Since there is no description in particular, it seems to be a service that can be used without authentication (no API Key required).
-
** POST or GET? ** ** This service uses the ** GET ** method. In the case where the method is not specified even at first glance of the specification like this time, it is determined as follows. --If there is a description to be used in the form of "endpoint (URL) + query parameter": GET in many cases --Other than that: Mostly POST
-
** What are the query parameters? ** ** It seems that you should specify the area (
city) for which you want to get the weather forecast. Let's use "Kurume: 400040" written in the sample. -
** What information should I send in the header / body? ** ** Since the GET method is used, there is no need to prepare a header body.
Python code sample
Now that you have the information you need for your request, let's make a request to the API in Python.
Send API request
It's okay if you copy and paste the code and execute it as it is.
#Library required for API request
import requests
#URL + query parameters
url = 'http://weather.livedoor.com/forecast/webservice/json/v1?city=400040'
#Send API request
tenki_data = requests.get(url).json()
Displaying the returned result with print () makes the display very difficult to read.
You need to understand how to use ** JSON data ** as it cannot be used as it is.
print(tenki_data)
Check JSON data of API response
The data returned from the API is often in ** JSON format **. I will omit the detailed explanation, but it is common to convert from JSON format to dictionary type in the .json () part included in requests.get (url) .json () of the code before using it. It is a target.
How to use the dictionary type is described in the API specification.
http://weather.livedoor.com/weather_hacks/webservice
First, it says that you can get the "title / heading" by specifying title in the dictionary type.
print('title:', tenki_data['title'])
Next, if you specify forecasts, you can get the" weather forecast for each forecast date ".
However, it requires a little complicated procedure peculiar to JSON format, so let's keep the flow together.
print(tenki_data['forecasts'])
First, when forecasts is specified, the list type whose first and last are enclosed in[]is displayed.
You can expect to specify here as "Today:[0], Tomorrow:[1], The day after tomorrow[2]" according to the data you want to acquire.
#Specify "Today" data
print(tenki_data['forecasts'][0])
It was pretty refreshing. If you come to this point, you can get the data you like according to the purpose, so let's display "Forecast date: dataLabel, Weather: telop" this time.
#Forecast date
print('Forecast date:', tenki_data['forecasts'][0]['dateLabel'])
#weather
print('weather:', tenki_data['forecasts'][0]['telop'])
In this way, a series of steps of "API specification check-request-response" will flow. You can get various other information, so please try various things by referring to the API specifications.
at the end
The point that APIs are used differently depending on the service is very troublesome. However, if you think based on the following introduced this time, you can master most of the API.
** Information required to use the API **
--Information for connecting to a Web service (obtained when registering the service) --API endpoint (URL to connect to the service) --API key (password required for connection) --Information to be sent to the Web service (can be confirmed in the API specifications)) --Method (mainly POST or GET) --Query parameters (specify details such as API / service type to use) --Header (Enter authentication information such as data type and API key * Specify by POST method) --Body (Enter the information you want to send and receive with the API. * Specify with the POST method)
** Confirmation procedure **
- What is the API endpoint?
- How to get API Key?
- POST or GET?
- What are the query parameters?
- What information should I send in the header body?
This is the end of "API mechanism and how to use it". I hope it will be useful information for your development.
- Various information is also posted on SNS, so if you feel that you can read the article, I would be grateful if you could follow Twitter account "Saku731".
~~ Also, at the end of the sentence, we are doing "** Team Development Experience Project **" for a limited time. ~~ ~~ If you are interested, please check [Application Sheet] for details. ~~ (Addition) The deadline has been closed because it is full. The next time is scheduled for March 2019, so if you would like to be informed, please fill in [Reservation Form].
Postscript (Supplementary materials will be added at any time)
--How to operate the Response object returned by the response - https://note.nkmk.me/python-requests-usage/ - http://python.zombie-hunting-club.com/entry/2017/11/06/211118#7-%E7%94%BB%E5%83%8F%E3%83%87%E3%83%BC%E3%82%BF%E3%82%92%E5%8F%96%E5%BE%97%E4%BF%9D%E5%AD%98%E3%81%99%E3%82%8B
--If the response is an audio file, use the following code to save it in WAVE format.
response = requests.post(API_Endpoint, data=json.dumps(body), headers=headers)
with open('response.wav', 'wb') as saveFile:
saveFile.write(response.content)
Recommended Posts