The two types of API designs. What is the correct API design. Questions for API designer.
You may have heard the phrase, "API is the plumbing that connects the Internet". At least we like to think so. When it comes to mobile app development, API is definitely the plumbing that connects mobile devices or internet devices to the cloud that feeds data and makes mobile apps work.
Those who program the API understand that if not done correctly application will perform poorly and will eventually cause a lot of heart burn. When designing the API, an architect needs to consider several things. What things? that is a subject I would take in a separate article, I want to focus on an architecture decision which is often discussed and debated. Below is my biased opinion. Don't take it as is. Consider your needs and decide what works for you.
So, what is the correct API design? Entity centric pure RESTful API or the more task focused DTO design? As always, the answer to that is, it depends. An API is designed to serve a purpose. The purpose is of utmost importance and helps in optimum design of the API. Consider the following questions that an API designed needs to answer before making an effective API.
Questions for API designer
- Is this API for general purpose integration or specific to an application?
- Is this public or private API?
- What is the expected load (calls per second) on the API?
- Is this API mission critical?
- Will this be providing real time or deferred data?
- How will the API evolve? How will it be versioned?
- How will it be really used?
What is Entity based RESTful architecture?
Entity is usually one object in a database table or a representation of a real world entity in software. Consider for example, a restaurant. The design which takes or returns entities is called entity based RESTful design and it primarily deals with exchanging objects.
Use of this design style is preferred when you are building a generic API for public consumption. Public API should be simple, consistent and predictable. For such design, a restful, entity based API design is most optimal unless your business is more task oriented. Here the focus is not on performance but on ease, consistency and future extensions without breaking existing clients.
What is DTO based API design?
Originally offered by Martin Fowler, a Data Transfer Object DTO focuses on reducing the number of calls and getting a task done. Use of this design style is preferred when you are building a private API for mobile apps. Here, a carefully crafted DTO style API is most optimal. The focus of this is performance, raw throughput and task based design, a task being for example, "Get all open restaurants".
Case Study: Instagram app home screen
Let's consider a typical mobile app home screen, in this case the Instagram app. The home screen shows the following:
- Posted Instagram image
- User's name
- User's avatar image
- Users location where image was taken
- Time image was posted
- Total likes for the image
- Total comments for the image including users who commented.
- 3-5 last comments
- Text posted by original user
If Post was a table, user was a table, comments was a table as commonly done in a relational design, to fetch last 20 screens via a restful entity based design would require:
- Fetch the last 20 posts (1 call)
- For each post, fetch user info, comments (1 call per user info, 1 per comments list)
- Fetch respective images, avatar (this is same in both designs).
So considering 20 posts, in an entity based restful design we will be making 41 data calls (1 primary call, 20 user info, 20 comments), 20 images and 20 avatar images (yes, I know we can optimize and not fetch same user info). However if you consider a DTO based design we will be making 1 primary data call and 20 images, 20 avatar loads only. All relevant data is returned in the primary data call. The user will see the data much faster and the server will also be hit one time instead of 41 times per screen. Apart from better app performance, let's not forget that with each call to server, the server needs to authenticate/authorize the access to particular resource which is additional work. Consider say 10,000 users, we are reducing 400,000 network hits to the server.
Not bad for a design decision.
RESTful Entity based design
Advantages
- Simple, predictable design
- Direct schema mapping
- Client controls workflow
- Random queries possible
- Easily extensible
Disadvantages
- Single operation requires multiple calls
- Aggregation, count and other operations difficult or not possible
- Larger network hit in mobile apps especially on complex screens
To overcome many of these problems especially for mobile apps where low latency, high performance is critically important, DTO based design is perfect and yields best results.
Data Transfer Object (DTO) Design
Advantages
- Highly optimized with minimum overhead
- Provides to the point, nested data with single call
- Provides pre-formatted, pre-processed data for the mobile
- Delivers highest performance
Disadvantages
- Application or task specific, not reusable
- Not intuitive to understand
- Adhoc queries not possible
How to choose
If you are building a mobile app and you expect a large volume of consumers, we cannot recommend anything other than a DTO based design. Even if you also require a public facing API, having a second mobile optimized private API has no parallels. The end user experience is so much better that it is well worth the extra effort for the convenience and pleasure of customer.
However if you are designing an API that will be used by several apps and possibly for general use as well, then a generic restful based design might be something to consider. I would probably choose a DTO based design in most cases for any mobile app designed for performance.