API Design Principals in Python

Share the joy
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

API Design Principals in Python

API Design Principals in Python

Source – Forbes

Standardized API design principals is a topic being discussed widely in the world today. It is one of the most important considerations tthat API developers and organizations need to check on when developing APIs. When it comes to designing APIs using Python, developers need to pay a lot of attention to certain design principals that will make sure that the API is successful. Python, being one of the most famous and accessible programming languages has been widely used in developing APIs. This shows a step by step guide on how to use an API with Python. 

API Design Principals in Python 

Usability and maintainability are the two most important aspects of a good API. This means that developers should observe these aspects if their APIs are to be successful. Apart from that, there are a few other design principals to be observed when developing APIs with Python. 

Designing Requests 

REST is the modern APIs prevailing design philosophy. It has become very popular due to the four methods defined by the HTTP protocol. The methods include GET, POST, DELETE, and PUT. These methods correspond to the traditional actions – READ, CREATE, DELETE, and UPDATE – that have long been used on data in a database.   

Many API design principals in Python revolve around ways through which requests are formatted. This is because HTTP requests are very important when using a REST API. To understand the API design principals in Python, we will start by looking at a poorly designed API endpoint.  

http://myapi.example.com/getartist/20 

There are several issues in the formatting of this request. First, we have a semantic error. This is because we are supposed to use the verbs GET, PUT, POST, or DELETE in a REST API. These verbs are determined by the request method, but not in the request URL like in our case above. This tells you that we should not have the word ‘get’ anywhere in our request. It is implied by using the HTTP GET method. It is also important to note that resource collections such as artists or users should always be denoted with plural nouns. This will make it clear for an API when it is referring to an entry (artist) or a collection (artists). Observing these principals, our endpoint above would now look like this:  

http://myapi.example.com/artists/20 

In the request above, we have used part of the path (/20) to give the ID. However, even though this approach is common, it is not one of the best approaches to use. This is because URLs constructed with this approach can only filter a field at a time. Your query parameters should allow filtering multiple database fields at a time and even have the capability to provide optional data. 

It is also important to plan for future additions when working on how requests to your API are to be structured. For example, if the current version of your API provides information on a single type of resource – artists in our case above, it is important to accommodate adding other resources or even non-resource functionality in the future as indicated below:  

http://myapi.example.com/resources/artists?id=20 

By adding an extra segment such as entries or resources on the path, as shown above, we have made it possible for users to search for all the resources available. This makes it possible for one to support more requests in the future.  

Finally, adding a version number to the path is a good way of planning for the future of your API. This makes it possible for you to keep supporting the old version of your API while releasing a newer version of the API. This will allow scripts and applications designed using the old version of your API to keep working even after you have released a new version. With all these design principals, a request to the API will look like this:  

https://myapi.example.com/v1-1/resources/artists?id=20 

Documentation 

An API, if not totally unusable, will still be very difficult to use if it lacks documentation. To make sure that your API is successful, you should have an API documentation that talks about the functionality and the resources that are available through the API. The documentation should also offer working examples of the requests and even code for the API, a section for each of the resources with the fields that it accepts, and an example on each section in the form of an HTTP request. An API documentation is one of the most important things to have when designing an API. 

Following above API design principals in Python, API development can be more successful and easy to adapt to the future changes as compared to the APIs that do not observe such design principals. 


Share the joy
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

Author: Firdaus

I work as an IT consultant in the Toronto area and I love to write blogs about a variety of subjects. My passion for writing stems from the desire that everyone should have access to meaningful information. Whether it is a blog about society, culture, technology, or social media, I don’t want to miss the opportunity of sharing my thoughts with my friends and audience. Since I believe in mutual exchange of ideas, I am always on the lookout for a feedback on my writings.

Share This Post On