current position:Home>Python can meet any API you need

Python can meet any API you need

2022-02-01 13:02:56 Huawei cloud developer community

​​ Abstract : The concepts and techniques learned in this tutorial will allow you to use whatever you like API Practising , And use Python To meet any needs you may have API Use requirements .

This article is shared from Huawei cloud community 《Python and API: Successful combination of reading public data 》, author : Yuchuan.

understand API

API representative Application programming interface . Essentially ,API Act as a communication layer , Or as the name suggests , An interface , It allows different systems to communicate with each other , Without accurately understanding each other's role .

API It can take many forms or shapes . They can be operating systems API, For example, turning on the camera and audio to join Zoom Call and other operations . Or they can be networks API, For network centric operations , For example, I like Instagram Images on or get the latest tweets .

Whatever the type , all API The functions of are roughly the same . You usually request Information or data ,API Meeting according to Your request returned Respond to . for example , Every time open Twitter Or scroll down Instagram The summary , You're basically talking to the... Behind the application API Make a request and get a response in return . This is also called call API.

In this tutorial , You will pay more attention to the advanced technologies of cross network communication API, Also known as Web API.

SOAP And REST And GraphQL

Although some of the examples mentioned above are for newer platforms or applications , but Web API It's been a long time . stay 1990 End of the year and 2000 s , Two different design models become the norm of public data :

1. **SOAP( Simple object access protocol )** Usually associated with the corporate world , With more stringent contract based usage , And it is mainly designed around operation .

2. **REST( Concrete state transmission )** Usually used for public API, It's from Web Ideal for getting data . It is better than SOAP Much lighter , And closer to HTTP standard .

Now , There is a new child in town :GraphQL.GraphQL from Facebook establish , Is a very flexible API query language , Clients can accurately determine what they want from the server , Not what the server decides to send .

If you want to learn more about the differences between the three design models , So here are some good resources :

  • What is soap ?

  • What is rest ?

  • API 101:SOAP And REST

  • GraphQL brief introduction

  • Compare API Architectural style :SOAP vs RESTvs GraphQL vs RPC

Even though GraphQL Is emerging and being adopted by more and more large companies , Include GitHub and Shopify, But the fact is that most public API Still REST API. therefore , For the purposes of this tutorial , You will only know REST API And how to use it Python Use them .

requests and API: A heaven-made match

Use Python Use API when , You only need one library :requests. With it , You should be able to perform any public API Most of the required ( If not all ) operation .

You can requests Install... By running the following command from the console :

$ python -m pip install requests
 Copy code 

​ Follow the code examples in this tutorial , Please make sure you are using Python3.8.1 and requests2.24.0 Or later .

Use Python Call your first API

Don't talk much —— It's time for your first API Called ! For the first example , You will call a popular API To generate random user data .

Throughout the tutorial , You will see the new... Introduced in the alarm block API, As shown below . This is a convenient way , After that, you can scroll through and quickly find all the new things you know API.

**Random User Generator API:** This is a good tool for generating random user data . You can use it to generate any number of random users and related data , You can also specify gender 、 Nationality and many other filters , These filters are useful when testing applications or in this case API It's very useful .

Start using Random User Generator API when , The only thing you need to know is which URL Call it . For this example , To be used URL yes randomuser.me/api/, This is where you can enter … API call :

>>>

>>> import requests
>>> requests.get("https://randomuser.me/api/")
<Response [200]>
 Copy code 

​ In this small example , You imported requests library , And then from URL Random user generator in API obtain ( Or get ) The data of . But you don't actually see any returned data . What you get is a Response [200], stay API The term means that everything is normal .

If you want to view the actual data , Then you can .text From the return Response Use in object :

>>>

>>> import requests
>>> response = requests.get("https://randomuser.me/api/")
>>> response.text
'{"results":[{"gender":"female",
"name":{"title":"Ms","first":"Isobel","last":"Wang"}...'
 Copy code 

​ this is it ! This is it. API Basic knowledge of consumption . You try to use Python and requests Library from random user generator API Get your first random user .

Endpoints and resources

As you can see above , Use API The first thing to know is API URL, Often referred to as basic URL. basic URL The structure is the same as what you use to browse Google、YouTube or Facebook Of URL There is no difference , Although it usually contains words

api. It's not mandatory , Just more rules of thumb .

for example , Here are some well-known API The basic of the player URL:

As you can see , All the above contents are in https://api And include the remaining official domains , for example .twitter.com or .github.com.API basic URL There is no specific standard for the appearance of , But it is common for it to imitate this structure .

If you try to open any of the above links , You'll notice that most of them return errors or ask for credentials . This is because API Sometimes authentication steps are required to use them . You will learn more about this in future tutorials .

**TheDogAPI:** This API Very interesting , But it's also a good example , It's a good API And good documentation . With it , You can get different dog breeds and some images , But if you register , You can also vote for your favorite dog .

Next , Use the just introduced TheDogAPI, You will try to issue a basic request , To see how it matches what you tried above Random User Generator API What's the difference? :

>>>

>>> import requests
>>> response = requests.get("https://api.thedogapi.com/")
>>> response.text
'{"message":"The Dog API"}'
 Copy code 

​ under these circumstances , When calling basic URL when , You will receive a general message , The content is TheDog API. This is because you are calling the basic URL, It is usually used in relation to API Very basic information , Not real data .

Call the basic function separately URL It's not very interesting , But that's where the endpoint comes in handy . One Endpoint Is to specify which URL Part of resources , You want to get . Well documented API Usually contains API Reference resources , This is for understanding API The exact endpoints and resources and how to use them are very useful .

You can check the official documentation for information on how to use TheDogAPI And more information about the available endpoints . There? , You will find one /breeds Endpoint , You can use it to get all available variety resources or objects .

If you scroll down , You will find the send test request section , You will see the form shown below :

​ This is where you will be in many API What you see in the document : A quick test directly from the document page API Methods . under these circumstances , You can click send to quickly get the result of calling the endpoint . wait , You just call API, Without writing any code for it .

Now? , Use a variety of endpoints and some that you already have API Knowledge tries code locally :

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds")
>>> response.text
'[{"weight":{"imperial":"6 - 13","metric":"3 - 6"},"height": ...}]'
 Copy code 

​ Okay , You use a dog API List your first variety !

If you are a cat lover , Please don't worry . One more API For your use , It has the same endpoint but different basic URL:

>>>

>>> response = requests.get("https://api.thecatapi.com/v1/breeds")
>>> response.text
'[{..."id":"abys","name":"Abyssinian"}]'
 Copy code 

I bet. , You are already considering using these API Different ways to make some lovely side projects , This is it. API The greatness of . Once you start using them , Nothing can stop you from turning your hobby or passion into an interesting little project .

As you move forward , One thing you need to know about the differences between endpoints http:// and https://. In short ,HTTPS yes HTTP The encrypted version of , Make all traffic between client and server more secure . Using public API when , You should absolutely avoid to http:// The endpoint sends any private or sensitive information , And use only those that provide security https:// basic URL Of API .

For online browsing, stick to HTTPS More information on the importance of , Please see how to use Python Explore HTTPS.

thereinafter , You will learn more about API The main component of the call .

Requests and responses

As you briefly read above , client ( In this case, it's your Python Console ) and API All interactions between are divided into request and response :

  • request Contains information about your API Data related to the request call , For example, basic URL、 Endpoint 、 Method used 、 Header, etc .

  • Respond to Contains the relevant data returned by the server , Include data or content 、 Status code and header .

Again using TheDogAPI, You can learn more about Request and Response The exact content inside the object :

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds")
>>> response
<Response [200]>
>>> response.request
<PreparedRequest [GET]>

>>> request = response.request
>>> request.url
'https://api.thedogapi.com/v1/breeds'
>>> request.path_url
'/v1/breeds'
>>> request.method
'GET'
>>> request.headers
{'User-Agent': 'python-requests/2.24.0', 'Accept-Encoding': 'gzip, deflate',
'Accept': '*/*', 'Connection': 'keep-alive'}

>>> response
<Response [200]>
>>> response.text
'[{"weight":{"imperial":"6 - 13","metric":"3 - 6"},
"height":{"imperial":"9 - 11.5","metric":"23 - 29"},"id":1,
"name":"Affenpinscher", ...}]'
>>> response.status_code
200
>>> response.headers
{'Cache-Control': 'post-check=0, pre-check=0', 'Content-Encoding': 'gzip',
'Content-Type': 'application/json; charset=utf-8',
'Date': 'Sat, 25 Jul 2020 17:23:53 GMT'...}
 Copy code 

​ The above example shows you what can be used to Request and Response Some of the most important properties of the object .

You will learn more about some of these properties in this tutorial , But if you want to dig further , Then you can view Mozilla Of HTTP Message document , For a deeper explanation of each attribute .

The status code

The status code is in any API One of the most important information to look for in the response . They will tell you whether your request was successful 、 Is there a lack of data 、 Missing credentials, etc .

as time goes on , You will identify different status codes without help . But for now , Here are some of the most common status codes you'll find :

​ you 200 OK I've seen in the example executed before , You can even 404 Not Found Identify by browsing the web .

** Interesting facts :** Companies tend to 404 Error pages are for private jokes or pure fun , As the following example :

  • MantraLabs

  • Gymbox

  • Pixar

  • Slack

however , stay API In the world , Developers have limited space to respond to this fun . But they make up for this elsewhere , such as HTTP header . You'll soon see some examples !

You can use .status_code And to check the status of the response .reason. The requests The library is still there Response Print the status code in the representation of the object :

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds")
>>> response
<Response [200]>
>>> response.status_code
200
>>> response.reason
'OK'
 Copy code 

​ The above request returns 200, So you can think of it as a successful request . But now look at the failed request that is triggered when you include a spelling error in the endpoint /breedz:

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breedz")
>>> response
<Response [404]>
>>> response.status_code
404
>>> response.reason
'Not Found'
 Copy code 

​ As you can see ,/breedz Endpoint does not exist , therefore API Return to one 404Not Found The status code .

You can use these status codes to quickly see if your request needs to be changed , Or should you check the document again for any misspellings or missing parts .

HTTP header

HTTP Headers are used to define some parameters for managing requests and responses :

​ When checking a request or response , You can also find many other headers . If you are curious about the specific purpose of each , Please check out Mozilla Extended list of .

To check the header of the response , You can use response.headers:

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds/1")
>>> response.headers
{'Content-Encoding': 'gzip',
'Content-Type': 'application/json; charset=utf-8',
'Date': 'Sat, 25 Jul 2020 19:52:07 GMT'...}
 Copy code 

​ To do the same for the request header , You can use response.request.headers because request yes Response Object properties :

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds/1")
>>> response.request.headers
{'User-Agent': 'python-requests/2.24.0',
'Accept-Encoding': 'gzip, deflate', 'Accept': '*/*',
'Connection': 'keep-alive'}
 Copy code 

​ under these circumstances , You did not define any specific headers when you made the request , Therefore, the default header is returned .

Custom title

You are using API Another standard you may encounter when using custom headers . These usually begin with X-, But not necessarily .API Developers usually use custom headers to send or request other custom information to clients .

** Interesting facts :** Some companies spare no effort to become interesting and innovative , Use... In a way they shouldn't HTTP header , For example, ask for a job application .

You can use a dictionary to define headers , And you can use headers Send them with your request .get().

for example , Suppose you want to ask API The server sends some requests ID, And you know you can use X-Request-Id:

>>>

>>> headers = {"X-Request-Id": "<my-request-id>"}
>>> response = requests.get("https://example.org", headers=headers)
>>> response.request.headers
{'User-Agent': 'python-requests/2.24.0', 'Accept-Encoding': 'gzip, deflate',
'Accept': '*/*', 'Connection': 'keep-alive',
'X-Request-Id': '<my-request-id>'}
 Copy code 

​ If you look through request.headers Dictionaries , You will be X-Request-Id Find some other headers at the end , These headers are any API The default header for the request . The response may have many useful headers , But one of the most important headers is Content-Type, It defines the content type returned in the response .

Content-Type Now? , majority API Use JSON As the default content type , But you may need to use the return XML Or other media types ( For example, images or videos ) Of API. under these circumstances , Content types will vary .

If you review the previous use TheDogAPI Try to check Content-Type header , Then you will notice how it is defined as application/json:

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds/1")
>>> response.headers.get("Content-Type")
'application/json; charset=utf-8'
 Copy code 

​ Except for certain types of content ( In this case application/json) outside , The header may also return the specified encoding of the response content .

**PlaceGOAT API:** This is a very stupid API, It returns goat images of different sizes , You can use it as a placeholder image in your web site .

for example , If you try from PlaceGOAT API Get an image of the goat , Then you will notice that the content type is no longer application/json, It is defined as image/jpeg:

>>>

>>> response = requests.get("http://placegoat.com/200/200")
>>> response
<Response [200]>
>>> response.headers.get("Content-Type")
'image/jpeg'
 Copy code 

​ under these circumstances ,Content-Type The title declaration returns JPEG Images . You'll learn how to view this in the next section .

The Content-Type The head is very important , You need to know how to handle the response and how to handle its content . There are hundreds of other acceptable content types , Including audio 、 video 、 Font, etc. .

Reply content

As you just learned , You are in API The content type found in the response will be based on Content-Type Header . In order to according to different Content-Type The header reads the response content correctly , The requests The package comes with several different Response attribute , You can use them to manipulate response data :

  • .text With Unicode The format returns the response content .

  • .content Returns the response content in bytes .

You have used .text Properties above . But for certain types of data , For example, images and other non text data , Use .content Usually the better way , Even if it returns the same result as Very similar .text:

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds/1")
>>> response.headers.get("Content-Type")
'application/json; charset=utf-8'
>>> response.content
b'{"weight":{"imperial":"6 - 13","metric":"3 - 6"}...'
 Copy code 

​ As you can see ,.content Same as before .text. however , By viewing the response Content-Type header , You can see that the content is

application/json;JSON object . For such content , The requests The library contains a specific .json() Method , You can use this method to API The byte response is immediately converted to Python data structure :

>>>

>>> response = requests.get("https://api.thedogapi.com/v1/breeds/1")
>>> response.headers.get("Content-Type")
'application/json; charset=utf-8'
>>> response.json()
{'weight': {'imperial': '6 - 13', 'metric': '3 - 6'},
'height': {'imperial': '9 - 11.5', 'metric': '23 - 29'}
...}
>>> response.json()["name"]
'Affenpinscher'
 Copy code 

​ As you can see , In execution response.json() after , You will get a dictionary , You can use Python Use it like any other dictionary in .

Now? , Review recent use of PlaceGOAT API Example of running , Try to get the same goat image and see its contents :

>>>

>>> response = requests.get("http://placegoat.com/200/200")
>>> response
<Response [200]>
>>> response.headers.get("Content-Type")
'image/jpeg'
>>> response.content
b'\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01\x01\x00H\...'
 Copy code 

​ under these circumstances , Because you are requesting an image ,.content So it's not very helpful . in fact , This is almost impossible to understand . however , You know this is a JPEG Images , So you can try to store it in a file , See what happens :

>>>

>>> response = requests.get("http://placegoat.com/200/200")
>>> response
<Response [200]>
>>> response.headers.get("Content-Type")
'image/jpeg'
>>> file = open("goat.jpeg", "wb")
>>> file.write(response.content)
>>> file.close()
 Copy code 

​ Now? , If you open a working folder , You'll find one goat.jpeg file , The file you just used API Get a random image of the goat . Isn't that amazing ?

HTTP Method

call API when , There are several different ways , Also known as Verb , Can be used to specify the action to be performed . for example , If you want to get some data , You can use the method GET, If you want to create some data , Then you will use the method POST.

When used purely API When consuming data , You usually stick to GET request , But here are the most common methods and their typical use cases :

​ These four methods are often called CRUD operation , Because they let you ç reate,[R EAD,ü PDATE and d elete resources .

** Be careful :** There's an extra PATCH The method is also related to CRUD Associated with the operation , But it's a little less than the above four methods . It is used to make some modifications , Instead of using full replacement resources PUT.

You can read more about the relationship between the two PUTPATCH And understand their different needs .

If you are interested in the rest HTTP The method is curious , Or you just want to know more about the methods already mentioned , So please check Mozilla Documents .

up to now , You only use for .get() get data , But you can also requests The package is used for all other HTTP Method :

>>>

>>> requests.post("https://api.thedogapi.com/v1/breeds/1")
>>> requests.get("https://api.thedogapi.com/v1/breeds/1")
>>> requests.put("https://api.thedogapi.com/v1/breeds/1")
>>> requests.delete("https://api.thedogapi.com/v1/breeds/1")
 Copy code 

​ If you try these on the console , Then you'll notice that most of them return 405Method Not Allowed The status code . This is because not all terminals will allow POST,PUT or DELETE Method . Especially when you use public API When reading data , You will find that most API Only GET request , Because you are not allowed to create or change existing data .

Query parameters

Sometimes , When you call API when , You get a lot of data that you don't need or don't need . for example , Calling TheDogAPI Of /breeds At the end , You will get a lot of information about a given variety . But in some cases , You may just want to extract some information about a given variety . This is where query parameters come in !

When browsing online , You may have seen or used query parameters . for example , Watching YouTube In the video , You have a similar

www.youtube.com/watch?v=aL5…. take v= stay URL That's what you said Query parameters . It is usually in the basic URL And after the endpoint .

To add query parameters to a given URL, You must ? Add a question mark before the first query parameter ( ). If you want to have multiple query parameters in your request , So you can use & Number ( &) To separate them .

alike YouTube There are multiple query parameters on the web address, which is like this :www.youtube.com/watch?v=aL5…

stay API In the world , Query parameters are used as filters , You can follow API Request sent together , To further narrow the response range . for example , go back to Random UserGenerator API, You know how to generate random users :

>>>

>>> requests.get("https://randomuser.me/api/").json()
{'results': [{'gender': 'male', 'name':
{'title': 'Mr', 'first': 'Silvijn', 'last': 'Van Bekkum'},
'location': {'street': {'number': 2480, 'name': 'Hooijengastrjitte'},
'city': 'Terherne', 'state': 'Drenthe',
'country': 'Netherlands', 'postcode': 59904...}
 Copy code 

​ however , Suppose you especially want to generate only random female users . According to the document , You can use query parameters gender=:

>>>

>>> requests.get("https://randomuser.me/api/?gender=female").json()
{'results': [{'gender': 'female', 'name':
{'title': 'Mrs', 'first': 'Marjoleine', 'last': 'Van Huffelen'},
'location': {'street': {'number': 8993, 'name': 'De Teebus'},
'city': 'West-Terschelling', 'state': 'Limburg',
'country': 'Netherlands', 'postcode': 24241...}
 Copy code 

​ That's great ! Now suppose you only want to generate female users from Germany . View the document again , You will find information about nationality Part of , You can use query parameters nat=:

>>>

>>> requests.get("https://randomuser.me/api/?gender=female&nat=de").json()
{'results': [{'gender': 'female', 'name':
{'title': 'Ms', 'first': 'Marita', 'last': 'Hertwig'},
'location': {'street': {'number': 1430, 'name': 'Waldstraße'},
'city': 'Velden', 'state': 'Rheinland-Pfalz',
'country': 'Germany', 'postcode': 30737...}
 Copy code 

​ Use query parameters , You can start from API Get more specific data , So that the whole experience is more in line with your needs .

To avoid rebuilding over and over again URL, You can use the params Property sends a dictionary of all query parameters to attach to URL:

>>>

>>> query_params = {"gender": "female", "nat": "de"}
>>> requests.get("https://randomuser.me/api/", params=query_params).json()
{'results': [{'gender': 'female', 'name':
{'title': 'Ms', 'first': 'Janet', 'last': 'Weyer'},
'location': {'street': {'number': 2582, 'name': 'Meisenweg'},
'city': 'Garding', 'state': 'Mecklenburg-Vorpommern',
'country': 'Germany', 'postcode': 56953...}
 Copy code 

​ You can apply the above to any other... You like API. If you return to TheDogAPI, There is a method in the document that allows you to filter the variety endpoint to return only varieties that match a specific name . for example , If you want to find a Labrador breed , Then you can use query parameters to implement q:

>>>

>>> query_params = {"q": "labradoodle"}
>>> endpoint = "https://api.thedogapi.com/v1/breeds/search"
>>> requests.get(endpoint, params=query_params).json()
[{'weight': {'imperial': '45 - 100', 'metric': '20 - 45'},
'height': {'imperial': '14 - 24', 'metric': '36 - 61'},
'id': 148, 'name': 'Labradoodle', 'breed_group': 'Mixed'...}]
 Copy code 

​ You have it ! By sending q with value The query parameters of labradoodle, You can filter all varieties that match this particular value .

** Tips :** When you reuse the same endpoint , The best practice is to define it as a variable at the top of the code . When you repeat with API Interaction time , This will make your life easier .

With the help of query parameters , You can further narrow the scope of the request and specify exactly what you want to find . Most of the things you can find online API All have some kind of query parameters , You can use them to filter data . Remember to view documents and API Reference to find them .

Learn advanced API Concept

Now you have a good understanding of using Python Use API Basic knowledge of , There are some more advanced topics worth exploring , Even short , For example, authentication 、 Paging and rate limits .

verification

API Authentication is probably the most complex topic covered in this tutorial . Although many public API Is free and completely public , But there is more behind some form of Authentication API You can use . There are many that require authentication API, But here are some good examples :

Authentication methods range from simplicity to clarity ( For example, using API Key or basic authentication method ) To more complex and secure technologies ( for example OAuth).

Usually , Call... Without credentials or with incorrect credentials API Will return 401Unauthorized or 403 Forbidden The status code .

API secret key

The most common authentication level is API secret key . These keys are used to identify you as API Users or customers and track your responses to API Use .API The key is usually sent as a request header or query parameter .

**NASA API:** The coolest public API One of the sets is composed of NASA Provided API . You can find API To get astronomical pictures of the day or earth multicolor imaging camera (EPIC) Pictures taken, etc .

For this example , You will use NASA Of MarsRover Photo API, And get the 2020 year 7 month 1 Photos taken on the th . For testing purposes , You can use DEMO_KEYNASA Provided by default API secret key . otherwise , You can go to NASA The Lord of API Page and click start to use to quickly generate your own API.

You can attach api_key= The query parameters will API Add the key to your request :

>>>

>>> endpoint = "https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos"
>>> # Replace DEMO_KEY below with your own key if you generated one.
>>> api_key = "DEMO_KEY"
>>> query_params = {"api_key": api_key, "earth_date": "2020-07-01"}
>>> response = requests.get(endpoint, params=query_params)
>>> response
<Response [200]>
 Copy code 

​ So far so good . You try to ask NASA Of API Make an authenticated request and get 200 OK Respond to .

Now look at this Response Object and try to extract some pictures from it :

>>>

>>> response.json()
{'photos': [{'id': 754118,
   'sol': 2809,
   'camera': {'id': 20,
    'name': 'FHAZ',
    'rover_id': 5,
    'full_name': 'Front Hazard Avoidance Camera'},
   'img_src': 'https://mars.nasa.gov/msl-raw-images/...JPG',
   'earth_date': '2020-07-01',
   'rover': {'id': 5,
    'name': 'Curiosity',
    'landing_date': '2012-08-06',
    'launch_date': '2011-11-26',
    'status': 'active'}},
  ...
}
>>> photos = response.json()["photos"]
>>> print(f"Found {len(photos)} photos")
Found 12 photos
>>> photos[4]["img_src"]
'https://mars.nasa.gov/msl-raw-images/proj/msl/redops/ods/surface/sol/02809/opgs/edr/rcam/RRB_646869036EDR_F0810628RHAZ00337M_.JPG'
 Copy code 

​ Use .json() Convert the response to Python Dictionaries , then photos Get the field from the response , You can traverse all Photo object , Even get images of specific photos URL. If you open the web address in your browser , Then you'll see Mars by a Mars probe that took the following pictures :

​ For this example , You can select from the response Dictionary ( ) Selected a specific earth_date( 2020-07-01), Then select a specific photo 4. Before proceeding , Try changing the date or from a different The camera Get photos , See how it changes the end result .

OAuth: introduction

API Another very common standard in authentication is OAuth. In this tutorial , You will only learn OAuth Basic knowledge of , Because this is a very broad topic .

Even if you don't know it is OAuth Part of , You may have seen and used... Many times OAuth technological process . Whenever an application or platform has a login mode or continue mode option , This is it. OAuth The starting point of the process :

​ Here's how to click continue Facebook Step by step breakdown of what will happen :

1. Spotify The application will require Facebook API Start the authentication process . So ,Spotify The application will send its application ID ( client_id) and URL ( redirect_uri) To redirect the user after success or error .

2. You will be redirected to Facebook Website , And ask you to log in with your credentials .Spotify The application will not see or cannot access these credentials . This is a OAuth The most important benefit .

3. Facebook Will show you Spotify All data requested by the app from your profile , And ask you to accept or refuse to share the data .

4. If you accept let Spotify Access your data , Then you will be redirected back to the logged in Spotify Applications .

In the implementation of the 4 Step by step ,Facebook To Spotify Provide a special credential ( access_token), You can reuse it to get your information . This particular Facebook The validity period of the login token is 60 God , But other applications may have different expiration dates . If you are curious , that Facebook There is a setup page , You can see which applications have received your Facebook The access token .

Now? , From a more technical point of view , Here's what you're using OAuth Use API What you need to know when :

  • You need to create one with ID(app_id or client_id) And confidential (app_secret or client_secret) Applications for .

  • You need to have a redirect URL ( redirect_uri),API Will use it to send you messages .

  • You will get a code as the result of authentication , You need to use it to exchange access tokens .

There are some variants on it , But generally speaking , majority OAuth Processes have steps similar to these .

** Tips :** When you just test and need some kind of redirection URL To get . when code, You can use the name httpbin Service for .

More specifically , You can httpbin.org/anything As heavy … URL, Because it only outputs anything it gets as input . You can navigate to this URL From line test .

Next , You'll delve into using GitHub API An example of !

OAuth: A practical example

As you can see above , The first thing you need to do is create an application . You can refer to GitHub file Detailed step-by-step instructions on how to do this in . The only thing to remember is to httpbin.org/anything Mentioned above … Used to authorize callback URL Field .

**GitHub API:** You can use GitHub API For many different use cases , For example, get the list of repositories to which you belong 、 Get the list of followers you have, and so on .

After creating the application , take Client_ID as well as Client_Secret The redirection you selected URL Copy and paste into a file named github.py Of Python In file :

import requests

# REPLACE the following variables with your Client ID and Client Secret
CLIENT_ID = "<REPLACE_WITH_CLIENT_ID>"
CLIENT_SECRET = "<REPLACE_WITH_CLIENT_SECRET>"

# REPLACE the following variable with what you added in the
# "Authorization callback URL" field
REDIRECT_URI = "<REPLACE_WITH_REDIRECT_URI>"
 Copy code 

​ Now you have all the important variables ready , You need to be able to create a link to redirect users to their GitHub account , Such as GitHub Described in the documentation

def create_oauth_link():
    params = {
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "scope": "user",
        "response_type": "code",
    }

    endpoint = "https://github.com/login/oauth/authorize"
    response = requests.get(endpoint, params=params)
    url = response.url
    return url
 Copy code 

​ In this code , You first define API Expected required parameters , And then use requests Bao He .get(). When you /login/oauth/authorize When the endpoint makes a request ,API Will automatically redirect you to GitHub Website . under these circumstances , You want to url Get parameters from the response . This parameter contains GitHub Redirect you to the exact URL.

The next step in the authorization process is to exchange the code you get for an access token . Again , according to GitHub In the document Steps for , You can create a method for it :

def exchange_code_for_access_token(code=None):
    params = {
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "redirect_uri": REDIRECT_URI,
        "code": code,
    }

    headers = {"Accept": "application/json"}
    endpoint = "https://github.com/login/oauth/access_token"
    response = requests.post(endpoint, params=params, headers=headers).json()
    return response["access_token"]
 Copy code 

​ ad locum , you POST Code that requests the exchange of access tokens . In this request , You must send your CLIENT_SECRETandcode In order to GitHub You can verify that this particular code was originally generated by your application . That's the only way ,GitHub API Will generate a valid access token and return it to you .

Now you can add the following to your file and try to run it :

link = create_oauth_link()
print(f"Follow the link to start the authentication with GitHub: {link}")
code = input("GitHub code: ")
access_token = exchange_code_for_access_token(code)
print(f"Exchanged code {code} with access token: {access_token}")
 Copy code 

​ If everything goes according to plan , Then you should get a valid access token as a reward , You can use it to call GitHub API, Impersonate authenticated users .

Now try adding the following code to use User API Get your user profile and print your name 、 User names and number of private repositories :

def print_user_info(access_token=None):
    headers = {"Authorization": f"token {access_token}"}
    endpoint = "https://api.github.com/user"
    response = requests.get(endpoint, headers=headers).json()
    name = response["name"]
    username = response["login"]
    private_repos_count = response["total_private_repos"]
    print(
        f"{name} ({username}) | private repositories: {private_repos_count}"
    )
 Copy code 

​ Now you have a valid access token , You need to use Authorization Header in all API Send it in the request . The response to your request will be a with all the user information Python Dictionaries . From this dictionary , The field you want to get name,login as well as total_private_repos. You can also print response Variable to see other available fields .

ok , It should be ! The only thing left to do is put them together and try :

 1import requests
 2
 3# REPLACE the following variables with your Client ID and Client Secret
 4CLIENT_ID = "<REPLACE_WITH_CLIENT_ID>"
 5CLIENT_SECRET = "<REPLACE_WITH_CLIENT_SECRET>"
 6
 7# REPLACE the following variable with what you added in
 8# the "Authorization callback URL" field
 9REDIRECT_URI = "<REPLACE_WITH_REDIRECT_URI>"
10
11def create_oauth_link():
12    params = {
13        "client_id": CLIENT_ID,
14        "redirect_uri": REDIRECT_URI,
15        "scope": "user",
16        "response_type": "code",
17    }
18    endpoint = "https://github.com/login/oauth/authorize"
19    response = requests.get(endpoint, params=params)
20    url = response.url
21    return url
22
23def exchange_code_for_access_token(code=None):
24    params = {
25        "client_id": CLIENT_ID,
26        "client_secret": CLIENT_SECRET,
27        "redirect_uri": REDIRECT_URI,
28        "code": code,
29    }
30    headers = {"Accept": "application/json"}
31    endpoint = "https://github.com/login/oauth/access_token"
32    response = requests.post(endpoint, params=params, headers=headers).json()
33    return response["access_token"]
34
35def print_user_info(access_token=None):
36    headers = {"Authorization": f"token {access_token}"}
37    endpoint = "https://api.github.com/user"
38    response = requests.get(endpoint, headers=headers).json()
39    name = response["name"]
40    username = response["login"]
41    private_repos_count = response["total_private_repos"]
42    print(
43        f"{name} ({username}) | private repositories: {private_repos_count}"
44    )
45
46link = create_oauth_link()
47print(f"Follow the link to start the authentication with GitHub: {link}")
48code = input("GitHub code: ")
49access_token = exchange_code_for_access_token(code)
50print(f"Exchanged code {code} with access token: {access_token}")
51print_user_info(access_token=access_token)
 Copy code 

​ When you run the above code, the following happens :

1. A link will be generated , Ask you to go to GitHub Page for authentication .

2. Follow this link and use your GitHub After logging in with credentials , You will be redirected to the callback you defined URL, It includes

code A field in the query parameter :

​1. After pasting the code in your console , You can exchange code for reusable access tokens .

2. Your user information is obtained using this access token . Print your name 、 Username and private repository count .

If you follow the above steps , Then you should get a similar end result :

$ John Doe (johndoe) | number of private repositories: 42
 Copy code 

​ There are many steps to perform , But it's important that you take the time to really understand each step . Most use OAuth Of API Will share many of the same behaviors , So when you start from API When reading data , A full understanding of this process will unleash a lot of potential .

Feel free to improve this example and add more features , For example, get your public and starred repositories or traverse your followers to identify the most popular repositories .

There's a lot about it online OAuth Excellent resources , If you use OAuth Behind the scenes API Is what you really need , Then I suggest you do more research on this topic . Here are some good starting points :

  • OAuth What is it ?

  • OAuth 2 Simplified edition

  • OAuth 2.0 Authorization framework

from API From the perspective of consumption , When you work with public API Interaction time , understand OAuth It will come in handy . majority API All use OAuth As its authentication standard , There is a good reason .

Pagination

Sending large amounts of data back and forth between the client and the server comes at a cost : bandwidth . To ensure that the server can handle a large number of requests ,API Usually use Pagination .

In very simple terms , Paging is the act of dividing a large amount of data into smaller parts . for example , Whenever you go to Stack Overflow On the question page in , You will see the following at the bottom :

​ You may realize this from many other websites , And the concepts of different websites are roughly the same . Specifically for API Come on , This is usually handled with the help of query parameters , There are mainly the following two :

1. One page, What page properties are you currently requesting to be defined

2. nail size Define the size attribute of each page

The specific query parameter name may be due to API Developers vary greatly , But the concept is the same . some API The player may also use HTTP Header or JSON Response to return the current paging filter .

Again using GitHub API, You can find... In the document that contains the paging query parameters event Endpoint . This parameter per_page= Define the number of items to return , and page= Allows you to page multiple results . Here's how to use these parameters :

>>>

>>> response = requests.get("https://api.github.com/events?per_page=1&page=0")
>>> response.json()[0]["id"]
'14345572615'
>>> response = requests.get("https://api.github.com/events?per_page=1&page=1")
>>> response.json()[0]["id"]
'14345572808'
>>> response = requests.get("https://api.github.com/events?per_page=1&page=2")
>>> response.json()[0]["id"]
'14345572100'
 Copy code 

​ Use the One URL, You can only get one event . But use page= Query parameters , You can continue to page the results , Make sure you can get all the events without making API overload .

The speed limit

Whereas API It's open to the public , Anyone can use , Malicious people often try to abuse them . To prevent such attacks , You can use a method called Rate limit Technology , This technique limits the number of requests that a user can make within a given time frame .

If you often exceed the defined rate limit , some API It may actually stop your IP or API secret key . Be careful not to exceed API Restrictions set by developers . otherwise , You may need to wait for a while before calling the command again API.

For the following example , You will use... Again GitHub API and /events Endpoint . According to its file ,GitHub About... Is allowed per hour 60 An unauthenticated request . If the value is exceeded , Then you will get 403 The status code , And it will not be possible to do any more... For a long time API call .

** Warning :** Running the next piece of code does prevent you from calling... For a while GitHub, So before running it , Please make sure you don't need to access GitHub Of API.

For demonstration purposes , You will purposefully try to surpass GitHub The speed limit of , See what happens . In the following code , You will request data , Until you get a status code other than 200 OK:

>>>

>>> endpoint = "https://api.github.com/events"
>>> for i in range(100):
>>>   response = requests.get(endpoint)
>>>   print(f"{i} - {response.status_code}")
>>>   if response.status_code != 200:
>>>     break
0 - 200
1 - 200
2 - 200
3 - 200
4 - 200
5 - 200
...
55 - 200
56 - 200
57 - 403
>>> response
<Response [403]>
>>> response.json()
{'message': "API rate limit exceeded for <ip-address>.",
 'documentation_url': 'https://developer.github.com/v3/#rate-limiting'}
 Copy code 

You have it : At about 60 After a request ,API Stop returning 200 OK Respond and return a 403 Forbidden Respond to , Notify you that you have exceeded API Rate limit .

some API( Such as GitHub Of ) It is even possible to include additional information about the current rate limit and the number of requests remaining in the header . These are very helpful for you to avoid exceeding the defined limits . Look at the latest response.headers, See if you can find those specific rate limiting headers .

Use Python Use API: Practical examples

Now that you know all the theories , And have tried some API, Then you can consolidate this knowledge with some more practical examples . You can modify the following examples to customize them for your own purposes .

You can learn these examples by downloading the source code provided in the following link :

Search and get hot GIF

How to make a small script , from GIPHY The website gets the top three hot GIF Moving graph ? So , You need to create an application and start from GIPHY obtain API secret key . You can find the description by expanding the box below , You can also view GIPHY Quick start documentation for .

establish GIPHY Application show hide

After you have mastered API After key , You can start writing some code to use this API. however , Sometimes you want to run some tests before implementing a lot of code . I know I know . The problem is , some API It actually provides you with access to... Directly from the document or its dashboard API Data tools .

In this special case ,GIPHY Provides you with a API Explorer, After you create the application , It allows you to start using API, Instead of writing a line of code .

Others API You will be provided with an explorer in the document itself , This is it. TheDogAPI At every API Refer to what you did at the bottom of the page .

in any case , You can always use code to use API, That's what you're doing here . Get... From the dashboard API secret key , By replacing API_KEY The values of the following variables , You can start using GIPHY API:

 1import requests
 2
 3# Replace the following with the API key generated.
 4API_KEY = "API_KEY"
 5endpoint = "https://api.giphy.com/v1/gifs/trending"
 6
 7params = {"api_key": API_KEY, "limit": 3, "rating": "g"}
 8response = requests.get(ENDPOINT, params=params).json()
 9for gif in response["data"]:
10    title = gif["title"]
11    trending_date = gif["trending_datetime"]
12    url = gif["url"]
13    print(f"{title} | {trending_date} | {url}")
 Copy code 

​ At the top of the file, on page 4 Xing He 5 That's ok , You defined your API_KEY Of API and GIPHYAPI,endpoint Because they don't change as often as other parts .

In the 7 That's ok , Use what you learned in the query parameters section , Definition params And add your own API secret key . You also include some other filters :limit obtain 3 Results and rating Get only the right content .

Last , After getting a response , You are on the 9 Row traversal results . For each GIF, You are on the 13 Line prints its title 、 Date and URL.

Running this code in the console will output a somewhat structured GIF list :

Excited Schitts Creek GIF by CBC | 2020-11-28 20:45:14 | https://giphy.com/gifs/cbc-schittscreek-schitts-creek-SiGg4zSmwmbafTYwpj
Saved By The Bell Shrug GIF by PeacockTV | 2020-11-28 20:30:15 | https://giphy.com/gifs/peacocktv-saved-by-the-bell-bayside-high-school-dZRjehRpivtJsNUxW9
Schitts Creek Thank You GIF by CBC | 2020-11-28 20:15:07 | https://giphy.com/gifs/cbc-funny-comedy-26n79l9afmfm1POjC
 Copy code 

​ Now? , Suppose you want to make a script , Allows you to search for a specific word and get the first... Of that word GIPHY Matches . The different endpoints and minor changes in the above code can do this quickly :

import requests

# Replace the following with the API key generated.
API_KEY = "API_KEY"
endpoint = "https://api.giphy.com/v1/gifs/search"

search_term = "shrug"
params = {"api_key": API_KEY, "limit": 1, "q": search_term, "rating": "g"}
response = requests.get(endpoint, params=params).json()
for gif in response["data"]:
    title = gif["title"]
    url = gif["url"]
    print(f"{title} | {url}")
 Copy code 

​ You have it ! Now you can modify this script to your liking and generate GIF. Try to get... From your favorite show or movie GIF, Add shortcuts to your terminal to get the most popular... On demand GIF, Or with your favorite messaging system (WhatsApp、Slack, wait ) Another in API Integrate . Then start sending... To your friends and colleagues GIF!

Get every country / Regional COVID-19 Confirmed case

Although you may be tired of it now , But there is a free API, It contains the latest global COVID-19 data . this API No authentication required , So it's very easy to get some data immediately . The free version you will use below has rate limits and some data limits , But it's enough for small use cases .

For this example , You will get the total number of confirmed cases as of the previous day . Again, I randomly chose Germany as my country , But you can choose any country you like / region :

 1import requests
 2from datetime import date, timedelta
 3
 4today = date.today()
 5yesterday = today - timedelta(days=1)
 6country = "germany"
 7endpoint = f"https://api.covid19api.com/country/{country}/status/confirmed"
 8params = {"from": str(yesterday), "to": str(today)}
 9
10response = requests.get(endpoint, params=params).json()
11total_confirmed = 0
12for day in response:
13    cases = day.get("Cases", 0)
14    total_confirmed += cases
15
16print(f"Total Confirmed Covid-19 cases in {country}: {total_confirmed}")
 Copy code 

​ In the 1 Xing He 2 That's ok , You can import the necessary modules . under these circumstances , You must import date and timedelta Object to get today's and yesterday's dates .

In the 6 Go to the first place 8 That's ok , You define the country to use / region slug、 Endpoint and API Query parameters of the request .

The response is a list of days , For every day , You all have one Cases Field containing the total number of confirmed cases on this date . In the 11 That's ok , You created a variable to hold the total number of confirmed cases , Then in the first 14 That's ok , You go through all the days and add them up .

The final print result will show the selected country / The total number of confirmed cases in the region :

Total Confirmed Covid-19 cases in germany: 1038649
 Copy code 

​ In this example , You're looking at the whole country / The total number of confirmed cases in the region . however , You can also try to view documents and get data for specific cities . Why not make it more thorough and get some other data , For example, the number of recovered cases ?

Search for Google The book

If you are passionate about books , Then you may need a way to quickly search for specific books . You may even want to connect it to your local library search , To see how to use the book ISBN Whether a given book can be found .

For this example , You will use Google Books API And public volume endpoints to perform a simple book search .

This is a moby dick Simple code to find words in the whole directory :

1import requests
 2
 3endpoint = "https://www.googleapis.com/books/v1/volumes"
 4query = "moby dick"
 5
 6params = {"q": query, "maxResults": 3}
 7response = requests.get(endpoint, params=params).json()
 8for book in response["items"]:
 9    volume = book["volumeInfo"]
10    title = volume["title"]
11    published = volume["publishedDate"]
12    description = volume["description"]
13    print(f"{title} ({published}) | {description}")
 Copy code 

​ This code example is very similar to the code example you saw earlier . From 3 Xing He 4 OK, let's start , Define important variables , For example, endpoint , In this case, it is the query .

issue API After the request , In the 8 Line start iteration result . then , In the 13 That's ok , Print the most interesting information for each book that matches the initial query :

Moby-Dick (2016-04-12) | "Call me Ishmael." So begins the famous opening...
Moby Dick (1892) | A literary classic that wasn't recognized for its...
Moby Dick; Or, The Whale (1983-08-16) | The story of Captain Ahab's...
 Copy code 

​ You can book Print the variables within the loop to see what other fields you have available . Here are some things that may help to further improve this code :

  • industryIdentifiers

  • averageRating and ratingsCount

  • imageLinks

Use this API An interesting challenge is to use your OAuth Knowledge and create your own bookshelf application , To record all the books you read or want to read . Then you can even connect it to your favorite bookstore or library , So as to quickly find the books sold near you from your wish list . It's just an idea —— I'm sure you can think of more .

Conclusion

About API, You can also learn a million other things : Different headers 、 Different content types 、 Different authentication technologies and so on . however , The concepts and techniques you learn in this tutorial will allow you to use whatever you like API Practising , And use Python To meet any needs you may have API Use requirements .

Click to follow , The first time to learn about Huawei's new cloud technology ~

copyright notice
author[Huawei cloud developer community],Please bring the original link to reprint, thank you.
https://en.pythonmana.com/2022/02/202202011302530992.html

Random recommended