A REST API Is Not Enough for Enterprise Mobile App Integration (Part 4 of 4)

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 API complexity, and surveyed the advantages of a more 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 for enterprise mobile, web, and IoT applications.

In this guide, we'll go over:

How It Works

Interactive Documentation

Comprehensive Administration

Complete Packages

Security, Scalability & Reliability

Building it for Real

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.

Related reading: What is API Integration?

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. This will require additional services for administration and an additional application as well.

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 REST API 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 across development, test, and production environments: 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. This is why companies should be a little wary of using Node.js for building backend APIs; it 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 many ways, the API endpoint is just the tip of the iceberg. It’s not enough. Much of what is needed to build a secure and scalable RESTful services backend is below the surface.

Related reading: RESTful API & Microservices

Building it for Real

If you’ve been following this four-part blog series, the line of reasoning we’ve explored should paint a clear, cautionary, and ultimately hopeful picture:

• Building your own REST APIs can snowball into a giant mess that adds to backend complexity and slows mobile and web development projects.
• Building APIs with REST API development tools, or trying to manage backend complexity with API management tools, doesn’t solve the root complexity problem, and adds an additional arbitration layer to the mess.
• Building comprehensive, reusable REST API services for groups of applications is possible with a carefully designed RESTful backend.
• A REST API endpoint it just the tip of the iceberg; it’s not enough for comprising a secure, reliable, and scalable RESTful backend.

This concludes my four-post series about the dangers of building your own REST API and the benefits of using a pre-built mobile backend as a platform for reusable and scalable RESTful services. I hope this series helps you make better decisions and understand some of the hidden risks of “rolling your own” RESTful services.

Related reading: Beyond API Management

Endnote

Why do I care so much about this? Because my company, DreamFactory Software, has been working on these problems for over a decade. We’ve struggled to solve these issues, over and over again. And it’s what inspired us to solve these problems once and for all by building the industry’s first open source mobile backend: the DreamFactory Services Platform. The DreamFactory Services Platform enables you to transform any data source into a comprehensive and well-documented palette of secure, customizable REST API services. And we’ve already built in deep support for a wide variety of backend data sources, including SQL and NoSQL, file storage systems, and external services.

To simplify front-end development, the DreamFactory Services Platform also generates client SDK code for every major development environment. And security is delivered by working with your own user authentication schemes with built-in services for user management, application hosting, record-level access control, and server-side scripting. As a free, open source software package, DreamFactory can be installed on any server, in the cloud, or on premises. And in addition to great community support, we offer professional product support services.

So when it comes to your REST API strategy for mobile and web application integration, you now have a choice. You can continue trying to build and manage your own APIs (with all the pitfalls it brings) or you can use a free, open source backend that provides a comprehensive palette of secure, scalable, customizable RESTful services for any data source in minutes.

The choice is yours. I sincerely hope you give the DreamFactory Services Platform a try. It’s working great for thousands of organizations already. I’m curious to hear how well it works for you — drop me a line in the comments below this blog.