Table of Contents for
RESTful Rails Development
RESTful Rails Development
Published by
O'Reilly Media, Inc., 2015
- Cover
- nav
- RESTful Rails Development
- RESTful Rails Development
- section
- Preface
- Preface
- 1. From Hypertext to Hyperdata
- 2. Getting Started with Ruby on Rails
- 3. First Adventures in API Design
- 4. The REST of the World
- 5. Designing APIs in RoR
- 6. Asynchronous REST
- 7. Testing RESTful Services
- 8. Microservices and Microapplications
- 9. Mapping Data Streams onto an Application UI
- 10. Deploying an API
- 11. Managing an App Ecosystem
- 12. Consuming Data Streams: Integrating External APIs in Your Application
- 13. Device-Independent Development
- 14. Data Analytics
- 15. Scaling Gracefully
- 16. Privacy and Security
- A. HTTP Quick Reference
- Index
- About the Author
- Colophon
Chapter 11. Managing an App Ecosystem
Once a number of developers start using your API through their applications, you will notice that a community of interacting parties will start growing around your product. Applications and developers in your community might develop different or converging interests regarding your product, and a set of relationships will form that you will need to manage directly or indirectly. In this chapter we will analyze these relationships and explore what you can do to maximize the satisfaction of your direct and indirect customers. We will focus particularly on how data can help you manage your relationship with your customers and developer community.
API Management
Your API and the applications that are using it, no matter how many or few these may be, have created a community of interacting parties. This community is often compared to an ecosystem.
In ecology, an ecosystem is a biological community of interacting organisms and their physical environment. If we translate this concept to a system of developers, applications, and APIs, we can start to see the analogies with the natural world. In an app ecosystem, the parties forming it interact to form different relationships with various purposes: they exchange data streams and communicate with one another and, perhaps, the rest of the world. Figure 11-1 illustrates this idea.
When you start managing a complex application ecosystem, you have already built a successful API that other developers have started using and integrating into their projects. So first of all, take a moment to congratulate yourself on this achievement.
Once you have congratulated yourself, and maybe your team or organization, you can start analyzing the intricate network of relationships that you will have to build and therefore manage with the developers that are using your service.
Figure 11-1. An ecosystem where an API feeds different applications and services
As an example, let’s consider our Citywalks API, which uses the WikiCat and Wikipin APIs to create thematic walks. The Citywalks API also has a customer, the Walks app, which displays walks on maps.
This is a three-level relationship where a certain API feeds another service, which then feeds different parties. The end result of this is an intricate network of relationships. Such a network could eventually evolve into a kind of mesh of APIs and apps, where some APIs feed other applications, to the point where, by adopting open protocols, each node in the network shares data with the others (see Figure 11-2).
Note
A mesh network is a network topology in which each node (called a mesh node) relays data for the network. The nodes cooperate to distribute data throughout the network. For more information, see the Wikipedia article on mesh networking.
APIs Are Not Consumer Products
There is a small mental leap that you need to make when starting to develop an API, and that is recognizing that an API is not a consumer product (at least, not yet)—but it could feed a large number of different products with its data.
It is true that many products have APIs that are used to drive more users to their platforms, but per se an API is not a consumer product. It is an interface that is meant to be used by developers to build applications.
These applications may have anywhere from a few hundred to millions of users, but these will not be your direct customers. Ultimately, your API’s customers are the applications consuming it, which in turn will have users of their own.
Figure 11-2. Your API probably feeds a set of subscribers, or developers; each of them will have a number of customers
There are a number of key features of a successful application ecosystem. These are:
- A developer portal
- Generally speaking, a developer portal is a web app providing different tools and services to your developer community. These typically include API documentation, community forums, key provisioning, and general tools and suggestions to facilitate integration and support your community.
- Testing and quality assurance
-
A standard procedure to test applications and to assure quality is extremely important for both parties involved in the integration process.
With a testing procedure in place, the API provider can ensure that all applications adhere to its terms of service and quality standards and that no malicious activity can be performed by the applications. Also, you can make sure that you catch any issues before the app’s users do. Consider this a stress, quality, and security test for your API as well as for the new developer’s app.
- Application management
- Application management programs provide all the techniques and procedures needed to deploy an application and deliver optimal performance and operations, including best practices for app versioning and onboarding.
- Advertising services
- Some business models use advertisements to ensure a stable cash flow; others rely on external ad networks to help developers promote their projects. Advertising services therefore help both the service providers and their subscribers to effectively reach new users, drive adoptions, or just monetize their products.
- User management
- User management services constitute an important feature of any app ecosystem. There is in fact more to manage than just the end users of your developers’ projects: there are also roles within your platform and permissions to be managed to ensure that developer groups can operate efficiently.
- Analytics
- Analytics services are all those features that support data-driven decisions for your developers and your platform. These include monitoring, optimizing, and continuously enhancing your ecosystem.
Managing Your Community’s Happiness
We have said that managing an application ecosystem means managing different players on our platforms. At the highest level, we have the developers trying to integrate our services into their products. At lower levels, we have the application’s end users. Their satisfaction, at least partially, depends on our API, including its ability to scale to meet traffic demands and its availability.
We will start by introducing how to bootstrap a developer program. We will then explore how to measure application and API quality, and finally we will talk about user happiness.
Developer Programs
A developer program is a set of features and tools you provide to help developers get started creating projects with your API.
A developer program usually includes your API documentation and a suite of case studies to help developers produce their first “hello world” call with your API. These could involve just fetching a resource or posting a simple update. It is up to you to create interesting case studies.
There are different ways to create good documentation, and a number of tools are available to help. Some of these are often included in API management platforms and do some of the heavy lifting for you. In other simpler cases you may just want to go with a simple open source library. Some libraries even allow you to write documentation descriptions directly in your code and test cases.
In the previous chapter I mentioned apiDoc, a Node package that generates documentation for you right from your code. We will now see how to use it effectively to get started with a simple API project.
Getting started with apiDoc
Installing apiDoc is as easy as running:
$npminstallapidoc-g
Note
To run npm you need Node.js installed. You can download an installer for your system from the Node website.
Once apiDoc has been installed, you can easily add a bit of documentation to your code. For example, let’s say we would like to document the blocks API methods of the Wikipin API:
=begin@api {get} /blocks/:id Show Block@apiName ShowBlock@apiGroup Block@apiParam {Number} id Blocks unique ID.=end
Then we would have to run the apidoc command from our application folder in a terminal window to obtain the HTML documentation:
wikipinuser$apidoc-odoc/
This will generate everything in the doc/ folder.
If you then want to specify some more information regarding your API, you can create an apidoc.json file with the following information:
{"name":"WikiPin API","version":"1.0.0","description":"apiDoc inherit example"}
To apply the changes, run the previous command again:
wikipinuser$apidoc-odoc/
Then navigate to the doc/ folder to see your documentation in HTML format.
apiDoc is an easy tool that can really help you in generating explorable documentation for your API methods. You can also use it to sketch your methods before you actually code them and share the schematic of your API with other members of your team.
Creating a developer community
Writing useful and clean documentation is not the only important aspect of creating a developer program. Giving your developers tools to easily integrate with your service and access to support resources is also paramount.
Just think of how many times you have struggled yourself trying to understand some piece of documentation or trying to figure out if your code had a bug or it was something in the API you were trying to import. You really need to allow developers to come to you and ask questions, while also providing a place where they can discuss their experiences and share snippets of their code.
There are certainly different ways to do so. Some products or companies set up Stack Overflow categories (like Facebook, for example). Others prefer to have a forum on their developer portal where people can ask questions, or a GitHub issues page. What is important is that you provide a place where developers can come and ask for help or showcase their projects. This is a simple way to attract fellow developers and drive attention to your API product, and eventually also to your main product.
App and API Quality
There are a number of issues that arise once external applications start integrating your services. Firstly, you need to check if the way developers are using your API product adheres to your terms of service or usage agreement. While it is certainly a good thing that you have opened up your service to the web population, you need to make sure that you can provide a certain level of quality and reliability, and that you profit from the endeavor.
The terms of service set the boundaries for the number and types of operations that developers can perform with your API. Terms of service and developer agreements are written in legal jargon, but they also set some very technical limits that allow your product or business to be scaled gracefully.
A simple example is the situation where you are scaling your service according to the number of applications using it. In this case, you might decide to set a maximum number of API call per minute/hour/day. In fact, if you know that you will be able to provide a certain service for a certain number of applications as long as they do not make more than a certain number of API calls per hour, you will also know how to allocate resources proportionally to the actual number of active applications.
Another aspect of app quality management that you might want to consider is providing automated testing. Application testing is important for a number of reasons. Firstly, it allows you to make sure that developers are using your API methods according to the terms of service. Secondly, it enables you to search for common bugs in integrating your service. Thirdly, you might have built a number of test cases that will ensure that the developer’s app will work reliably on a number of platforms.
As part of your app or service testing framework, you can implement security policies. This simplifies the developer’s operations and makes sure that every application or API in your ecosystem will adhere to certain principles that you are comfortable with.
User Happiness
User happiness management involves using a set of procedures and tools to ensure that you and your developers can provide the desired level of satisfaction.
The first step here is understanding that you might not directly have end users. You might in fact be in a situation in which you are providing a service to a third party, and this party has its own user base.
A possible different scenario would instead be the situation in which you are providing a certain API to third-party developers, but their applications will be accessed through your main platform or product. In this case the end users of their apps will also be your product’s users.
In both cases you will have to manage different levels of relationships. On the one side, you need to ensure that developers are happy to create projects with your API; on the other side, you need to make sure that the end users are satisfied with the service they are ultimately using. Having a clear picture of how users interact with your APIs can help you to support developers and ensure the quality of their apps and APIs. Also, you can use the information you extract from your data to make intelligent decisions.
Data Management and Analytics
When managing an ecosystem of apps, APIs, developers, and users, you have a multitude of data sources that you might want to keep under control for various reasons.
For example, you might have a monitoring and analytics program in place that you can draw upon to make data-driven decisions. Questions like “How much traffic are our services producing?” and “How many requests are we receiving per second?” can be easily answered by carefully monitoring your backend and endpoints.
Also, once you can provide informative answers to questions like these, you can plan for the future. How many machines should you provision next month/year? To make these kinds of decisions, you will need accurate data.
Depending on your business models, you may need data for a variety of purposes.
One such purpose could be monetizing your API. In this scenario, your developers might pay you a certain amount to use your API, depending on the terms of their service contracts. These fees might be calculated on a pay-per-use basis, or on a tiered basis. Either way, you will need to know data like the number of requests per developer or application, and general usage statistics.
Another reason why you may want to build a strong reporting infrastructure is for marketing. You might want to suggest products or services through your API, or you might want to provide the possibility for your developers to advertise through your API. In such scenarios, you might want to collect end user data.
Another possible reason would be for providing statistics to the end users. A possible scenario where this could be important is one in which the developers creating apps on your platforms are also your business partners and are selling some services on your behalf.
Business intelligence, statistics, and reporting are all legitimate reasons to justify an investment in data management and analytics to capture event data. Event data can really be anything: signups, upgrades, impressions, purchases, errors, shares—these represent those constant little interactions that happen all day, every day, in any application.