There are a lot of great API managers available. Starting with the A’s, we have Akana, Apigee, AWS and Azure, among others. The first part of this post explores how you can use the DreamFactory REST API Platform with almost any API manager. The second part explores scenarios where DreamFactory is a more effective way to engage developers than an API management solution.
API managers are often used to expose REST APIs to an internal or external group of developers. An internal group of enterprise developers might use a catalog of API services as a starting point for software development projects. An external group of partners might use the APIs for integration with their backend systems. In some cases, partners might use the APIs to purchase goods, services, or information.
An administrator adds any number of services to the API management catalog. They need to enter REST URLs, select HTTP verbs, and write documentation for each service. Then developers or partners are invited to the portal. When someone goes there, they see a catalog of the APIs they can use. They can interactively test out the services, or get code samples showing how to call the APIs from different languages.
API managers are very good at listing API services, governing API access, providing documentation, metering usage, and in some cases, charging subscription fees. An API manager is similar to an API marketplace, where developers can go to browse publicly available services.
The API manager acts as a proxy gateway. When a service in the catalog is called, the API manager invokes the actual REST API, waits for a response, and then relays the results back to the original caller. This is how an API manager tracks usage and limits access to the various services in the catalog.
The services listed by an API manager are not usually appropriate for mobile application development. The problem is that using an API manager introduces an additional proxy relay on top of the underlying service. This means that the service is often too slow for transactional mobile applications where the round trip delay needs to be a half second or less.
API managers mainly provide a service catalog. For a modern developer to actually use the services, they have to build out a runtime platform for application hosting, create a user management system, develop role-based access controls, etc. For this reason, API management systems are often used for backend integration scenarios. The services are mainly intended as building blocks for other servers to use. This reflects the SOA heritage of many API management companies.
DreamFactory works with almost any API management system. You can expose a comprehensive REST API for any SQL database, NoSQL document store, or external File System in minutes. Role-based access controls, server-side scripting, and data orchestration capabilities can be used to customize the service if needed.
First, create an application in the DreamFactory admin console and assign it a default role. Then use the API Key for that application as a URL parameter in the API Management system. This provides access for unauthenticated users to all of the services enabled by that role. The API Key will be “hidden” by the API manager, so access will be limited to the developers who are invited to the portal.
When documenting the service, be sure to list the URL parameters that developers will need to know about. This lets them customize many aspects of the REST API call. The parameters for a given service are explained in the Live API section of the DreamFactory admin console. The API manager will pass these parameters to DreamFactory when the service is called.
When you connect a database to DreamFactory, the request URL for the service will look something like this:
www.server.com/version/database/table?param=value
The “database” path name is a label for the database, and the “table” path name is one of the tables in that database. Some API managers support flexible path names like this. In that case, you can expose multiple database tables with one listing in the API manager catalog. Other API managers do not support flexible path names, and in that case you will need to create a separate listing for each database and table that you want to expose.
Here is a picture of hooking up a DreamFactory service to the Azure API manager. As you can see, the API manager adds the API Key to the URL when the service is called. Security is enforced by the database user login, the secret API Key, and the API manager credentials.
As mentioned earlier, there are times when you should use a DreamFactory development environment instead of an API manager. If you are trying to expose live API services and engage modern application developers then a DreamFactory development environment is probably the right choice. If you are trying to expose API services without application development capabilities to server-side developers, an API management portal may be a better choice.
Some visual aids will help illustrate the difference. Below is a view of the developer portal in the Microsoft Azure API Management system. You can see a listing of the available services and try them out interactively. Code snippets are provided for calling the services.
Next, here is a DreamFactory developer environment. A modern developer can either sign up at the portal or be invited. They are presented with a runtime platform for building mobile, web, or IoT applications. The platform is pre-loaded with all of the services that they need for modern application development. They can invite other administrators, manage end users, create user roles, and onboard other services as needed for integration. They can use server-side scripting to customize existing services or develop custom services if needed.
There is a listing of the available services under the API Docs tab. The listing can include SQL and NoSQL database services, Third-party services like Twilio and Stripe, or other external REST or SOAP services that have been added to the environment. DreamFactory supports the Swagger API documentation system to list and interactively try out the services. Here is an illustration of the service catalog and documentation interface.
One advantage to the DreamFactory development environment is that the platform is directly connected to the data sources. This is consistent with DreamFactory’s primary focus on providing transactional API services for massively scalable runtime environments. API management systems require an additional HTTP proxy relay for each call that passes through the gateway. That can introduce speed and scalability concerns.
Here is a matrix that illustrates the differences between an API management portal and a DreamFactory developer environment.
| DreamFactory Developer Portal | API Management Tool | |
|---|---|---|
| Targets | Application Developers | Server Developers |
| Listing of Available APIs | ✓ | ✓ |
| Live Documentation of APIs | ✓ | ✓ |
| Auto-generate SQL and NoSQL APIs | ✓ | |
| Scripting & Customization | ✓ | |
| Building Custom APIs | ✓ | |
| Admin & User Management | ✓ | |
| Enterprise Service Integration | ✓ | |
| AD, LDAP, and OAuth Integration | ✓ | ✓ |
| External Services (REST, SOAP) | ✓ | ✓ |
| Orchestrate Multiple APIs | ✓ | |
| Track APIs, Usage Reporting | ✓ | ✓ |
| API Limits and Throttles | ✓ | ✓ |
| Role-Base Access Control | ✓ | |
| Application Hosting | ✓ |
If your audience is a client-oriented modern software developer, then an instant developer environment makes a lot of sense. Here are some popular use case scenarios for using DreamFactory.
Companies often have different departments building different types of applications. With DreamFactory, the IT staff can create and maintain different packages that are appropriate for each type of application. Citizen developers can log into the corporate portal, select a package, and construct a modern application immediately. The API services in the catalog and the access rights to various databases can be pre-approved and curated by IT administrators. This “decouples” backend server side administration from front-end application development, bringing dramatic savings in the time and cost required for application development.
Many companies have API services that they promote to developers. For example, Twilio has communication services and Stripe has financial services. In the past, service providers could list their services on a website or an API marketplace. With DreamFactory, they can provide a complete developer environment instead. A developer can sign up and instantly get access to a sandbox with a predefined set of third-party services. This is a powerful way to engage modern developers, promote adoption of an API, increase workloads for commercial services, conduct developer hackathons, etc.
DreamFactory not only provides the pre-defined services, but also provides all of the other infrastructural services needed for actual software development. These capabilities include user management, role-based access control, example applications in different frameworks, application hosting capabilities, server-side scripting, and more. This significantly lowers the barriers for developers to adopt a third-party service. Instead of just listing the services, they can be used “live” in the context of an actual application. Finished projects can easily be moved from the sandbox to a dedicated server using the DreamFactory package manager.
API management is a good way to make REST API services available to a partner. But in other situations, they might need more than that. For example, a partner might want to control administrative access to the services at their own company. Or they might want to implement role-based access to the services among their own developers. They might want to customize the services themselves, or implement workflow triggers when certain services are used. They also might need to perform enterprise integration with their own databases or other external services. By giving a partner access to a DreamFactory developer environment, all of these scenarios can be implemented in a simple and direct manner.
The DreamFactory developer environment can include more than just useful services. The package can also contain ready to use mobile applications, complete with backend hosting. This is a powerful way to distribute a set of mobile applications to the partner. They can administer user roles and control access to these applications. The applications are working examples of how to interact with the REST API services on the platform. A partner can explore the source code and customize the applications if needed.
As you can see, DreamFactory offers much more than the aggregation options of an API management platform. It’s a comprehensive backend solution for mobile, web, or IoT applications and provides a powerful way to engage modern application developers.