Tue: APIs and requests package

The internet has lot information. As users of the internet, we can easily see and deduce the meaning of the implicit information. However, this is almost impossible for the current technology, short of machine learning and quantum computing. APIs(Application Program Interface) are created to solve this particular problem. How does API make this problem? The clue is in the name; Interface. the interface describes how and where the computer devices should connect to the particular resource. The most commonly used interface is HTTP and derivatives i.e SOAP. The API also describes the form of the data would be transmitted from the server to the client. The forms of transmission include JSON and XML. the API should also describe the particular path to find the information, mostly accomplished using URI paths. In this manner, the API has enabled the computer to know how to get information, where the data is stored and how to process the information.

The biggest shortcoming of API design is the lack of a gold standard. The API design and behavior is largely dependent on the developer. Therefore, the developer has to document the API. the documentation acts a guide on how the implement that particular API. It should contain all the available resources, the parameters needed to manipulate result and the format of the result
Example API docs:

API endpoint: https://www.teamleader.be/api/addSubscription.php

Required POST parameters for new subscriptions

contact_or_company: contact or company: Who is the subscription for?

contact_or_company_id:integer: ID of the contact or company

sys_department_id: ID of the department the invoice will be added to

date_start: date (dd/mm/yyyy): date the first invoice should be created.

repeat_after: Pick one: monthly, twomonthly, quarterly, sixmonthly, yearly, twoyearly

title: String (eg: Hosting, Domain names,..)

from:http://apidocs.teamleader.be/subscriptions.php

Accessing API in Python

In this particular instance, I am using http://universities.hipolabs.com API. This API provides data including name , domain, and country of a university. It also allows for the filtering of the data based on either country and/or partial name.
Sample output from the API as below:

[
    ...
    {
        "alpha_two_code": "TR",
        "country": "Turkey",
        "domain": "sabanciuniv.edu.tr",
        "name": "Sabanci University",
        "web_page": "http://www.sabanciuniv.edu.tr/"
    },
    ...
]

Accessing HTTP API from Python

HTTP client libraries are use to access API design to use HTTP specification. One of the clients used in Python is requests module.

Example code:

import requests

def test_api():

     #program connecting to a resource 
     #status code and parsing the response to json.

     response = requests.get("http://example.com/path/to/resource")
     print response.status_code     #http status_code 200=success
     print response.json()          #convert response to json

HTTP status code are used to convey the state of the request:

10x : server communication
20x: successful connection
30x : redirection
40X : content errors
50x: server errors

API should communicate with the client on the result of the request and should provide clear message to that effect. These messages help the developers using it to locate the source of errors

Conclusion

API form a bridge between computers to computer communication
Good documentation should describe the available resources, parameters, and smaple output of an API
request module is among the many HTTP libraries that may be used to access HTTP APIs