Table of contents

My first three blogs in this series discussed the perils of building your own REST API, looked at some ineffective solutions that companies use to battle backend complexity, and surveyed the advantages of a comprehensive and reusable API strategy. Now in Part 4, I want to consider some of the additional issues that companies will need to consider if they want to build a complete backend platform.



How Does This Work?

Each API needs to be documented so that client developers can understand how to use the service. There will be different URLs for each application in development, testing, and production. Each URL will have identifiers for different types of resources. There will be required or optional URL parameters that take various arguments. Each service will have HTTP verbs that identify the allowed operations on the resource.

4_of_4_image

Most services return a JSON or XML document. Some services also require a document when they are called, for example, if you are creating database records. Client developers will need to understand the format of all of these requests and responses. This is a difficult problem to solve, because the format will be different based on various parameters and the backend database involved.

Interactive Documentation

Sitting down with a technical writer and documenting a sophisticated and dynamic API is bound to be error prone. A self-documenting API system is a better solution. If the documentation is online and interactive, then developers can quickly try out requests and responses, and see the different patterns of API usage.

Going further, your REST API should have a Client SDK that simplifies access for native mobile and HTML5 developers. A Client SDK can enable developers to leverage the REST API definitions and quickly write software in their native language for any target device or framework.

Comprehensive Administration

Custom-built REST API platforms are often administered with server logs and command line operations. Someone might need to manage users, change permissions, configure services, upload applications, or create server-side business logic. These activities require highly technical personnel to maintain the system.

A better answer is to write an administrative console that enables less technical developers and designers to quickly change the backend platform. The admin console can also allow partners and end users to make some changes when appropriate. Third party developers can use the development environment without access to master database credentials.

But creating an admin console for your REST API is serious work. Many of the capabilities of an admin console should also be available as RESTful services. So one secure way to proceed is to write a suite of administrative services for your backend and build the admin console on that platform.

The Complete Package

Building a REST API is one thing, but often companies will need some degree of portability for the system as well. If they decide to change cloud vendors or move an application from the data center to the cloud then they also need to move all of that backend code. Custom-built REST APIs tend to have hard wired connections to various databases and pieces of backend infrastructure that can make this difficult.

Ideally your backend can be installed almost anywhere, including IaaS clouds like Amazon, Azure, or Google, PaaS destinations like Heroku and OpenShift, and even on desktop computers like OS X, Windows, and Linux. This enables extreme horizontal portability: developers can build applications on a desktop computer, system administrators can run the platform anywhere, and partners or customers can run and manage their own installations when necessary.

Security, Scalability, and Reliability

Anyone building their own REST API will need to address the issues surrounding security, scalability, and reliability. There is a real potential for nasty surprises as your implementation is rolled out to hundreds, thousands, or millions of users.

For security, the user role and permission system needs to be rock solid. Can you handle record-level access control? Are you preventing SQL injection attacks? Does your platform handle SSL and CORS correctly? Is the single sign-on system airtight? What about credential management? Can the URL routing engine be exploited? Is the server-side scripting system secure?

Your REST API will need to scale both horizontally and vertically. Additional servers behind a load balancer should result in more transactions per second. Increases in processor speed or available memory should result in faster transaction times. The process threading architecture needs to support this goal. For example, Node.js isn't multi-threaded, which limits scalability.

Lastly, system reliability is very important for transactional hosting. Do you handle exponential backoff during a DOS attack? Can you place limits on service transactions to govern usage from a particular client? Can you monitor the backend platform for service outages? Can you handle a server-side script that takes too long to run? Can you paginate database transactions that are too big? Can you report on services that are failing, being called too much, or transacting too much data?

In Conclusion

This concludes my four part blog about the dangers of building your own REST API and the benefits of using a pre-built mobile backend. I hope this series has helped companies make better decisions and understand some of the hidden risks of “rolling your own” RESTful services.