RESTful APIs through the lens of mobile app systems
REST or RESTful API design (Representational State Transfer) is designed to take advantage of existing protocols.Nothing is worse than thinking that you’ve completed a new endpoint before realizing it’s not in a format the mobile client can use efficiently.Before we dive into the hosting, security, architecture, and other considerations for creating your RESTful API, let’s examine what makes building an API for mobile apps different from other systems. These mobile-specific concerns are essential to making sure your RESTful API is prepared to work efficiently with a mobile app and the expectations of its users.Mobile platforms enforce HTTPS requirements with modern encryption and trusted signed certificates.Your development, staging, and production environment servers should all be using the same type of signed certificates.Mobile app users expect their data to be synced across all their devices, which is also solved by moving the data off the device with an API.
A useful communication avenue unique to mobile is the push notification. There are third party tools that specialize in push notification, but sometimes you need to manage the process yourself. Your server may be responsible for tracking device tokens that maps devices to users for sending push notifications.
REST APIs are stateless, meaning that calls can be made independently of one another, and each call contains all of the data necessary to complete itself successfully.
Stateful design:Below figureillustrates a stateful service from which an application may request the next page in a multipage result set, assuming that the service keeps track of where the application leaves off while navigating the set. In this stateful design, the service increments and stores a previousPage variable somewhere to be able to respond to requests for next.
Stateless design:A stateless Web service generates a response that links to the next page number in the set and lets the client do what it needs to in order to keep this value around. This aspect of RESTful Web service design can be broken down into two sets of responsibilities as a high-level separation that clarifies just how a stateless service can be maintained
Keep your API concise and modular:
The actions GET, POST, PUT, PATCH, DELETE are the HTTP methods telling the server what action to perform.The URL path itself tells which are the resources that will be acted on. It’s important to make this distinction here, because otherwise you could end up with a messy API that’s difficult to follow.API versioning is another feature we should implement to achieve the robustness that is especially important for mobile apps.
Requests and Responses:
Content-Type and Accept headers in the request will likely remain application/json for most requests. Other types of resources like files, images, audio, etc. should have their content type set and respected here as well.After handling the request, we need to send a response. Maybe the request was processed successfully or something may went wrong. This is where the response HTTP status code helps us out.The HTTP standard provides over 70 status codes to describe the return values. We don’t need them all, but there should be used at least a mount of 10.
200 – OK – Eyerything is working
201 – OK – New resource has been created
204 – OK – The resource was successfully deleted
304 – Not Modified – The client can use cached data
400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. „The JSON is not valid“
401 – Unauthorized – The request requires an user authentication
403 – Forbidden – The server understood the request, but is refusing it or the access is not allowed.
404 – Not found – There is no resource behind the URI.
422 – Unprocessable Entity – Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the stracktrace should be logged and not returned as response.
Use a well-known architecture:
RESTFul Web Services serves JSON that is faster to parse than XML.RESTFul web services can also serve XML and any MIME type that you desire.REST uses the underlying technology for transport and communication between clients and servers.The architecture style is optimized for the modern web architecture.It will utilize the features available in HTTP such as caching, security in terms of TLS and authentication.
The fundamental concept in any RESTful API is the resource.The diagram below illustrates the key concepts in a RESTful API.The information that describes available resources types, their behavior, and their relationships is the resource model of an API. The resource model can be viewed as the RESTful mapping of the application data model.Resources have data associated with them. The richness of data that can be associated with a resource is part of the resource model for an API.REST metadata includes other information that is specific to the RESTful API. Such information includes URLs and relationships.JSON, YAML, XML and HTML are common representations for resources.
Version your API:
Make the API Version mandatory and do not release an unversioned API. Use a simple ordinal number and avoid dot notation such as 2.5.
There are three common approaches to implement API versioning:
- Resource versioning: the resource representations are versioned while keeping resource URIs the same.
- URI versioning: the version is part of the URI, either as a prefix or suffix.
- Hostname versioning: the version is part of the hostname rather than the URI.
Account for offline usage:
Making your mobile app work offline means that you try to provide, as much as possible, the same user experience whatever the network condition is: up, down or even slow or inconsistent in speed.We can implement offline mode in three steps.
- Storing the data locally
- Leveraging http caching mechanisms
- Creating notes while offline
Choose the Right API Security Protocol:
Basic API authentication is the easiest to implement, because the majority of the time, it can be implemented without additional libraries.OAuth 1.0a is the most secure among the common protocols. OAuth1 is a widely-used, tested, secure, signature-based protocol.The protocol uses a cryptographic signature, (usually HMAC-SHA1) value that combines the token secret, nonce, and other request based information.OAuth2 sounds like an evolution of OAuth1, but in reality it is a completely different take on authentication that attempts to reduce complexity. OAuth2’s current specification removes signatures, so you no longer need to use cryptographic algorithms to create, generate, and validate signatures. All the encryption is now handled by TLS, which is required.
Let the API user specify its preferred language in the Accept-Language HTTP header. For example, Accept-Language: da and then the REST API should automatically translate it into Danish:
Provide filtering, sorting, field selection and paging for collections:
- Filtering: Use a unique query parameter for all fields or a query language for filtering.
- Sorting: Allow ascending and descending sorting over multiple fields.
- Field Selection: Give the API consumer the ability to choose returned fields. This will also reduce the network traffic and speed up the usage of the API.
- Paging: Use limit and offset. It is flexible for the user and common in leading databases.
Exposing a system’s resources through a RESTful API is a flexible way to provide different kinds of applications with data formatted in a standard way. It helps to meet integration requirements that are critical to building systems where data can be easily combined (mashups) and to extend or build on a set of base, RESTful services into something much bigger.