LinkedIn
Twitter
Last week, @Steve Traut introduced StreetCarts, an end-to-end API project that the Apigee docs team is building. This article describes the kinds of up-front planning and design issues we've been thinking and asking about.
In the next few weeks, we'll drill into the details of our project, aided along the way by a team of Apigee expert advisors and, we hope, the entire Apigee Community! Please feel free to ask questions and contribute your own experiences to this thread.
The Data
We created a StreetCarts data store in Apigee API BaaS. The data includes FoodCarts, Menus, MenuItems, Users, Reviews, Orders, Favorites, and more, modeled as collections. We’ll build APIs that allow us to unlock this data, making it available to developers and the people who use their apps.
Some of the data will be public, and some will require authentication to gain access. One of our goals is to design our API layer so that we could use a different data store if we wanted without changing the APIs themselves, a key design principle.
The User Experience
Naturally, we started by thinking about what users want to do. It’s pretty simple: Users want to find something good to eat! They want to find the food carts nearby, see the menus and prices, read and write reviews, place orders, perform custom searches, and so on. But there’s more. There are different kinds of users:
- Unregistered users: Just show me the food carts, where they are, what they serve, and how much it costs.
- Registered users: I found the food, now let me place an order! Let me write a review! Let me share my experience with others! I have to register and log in to do this stuff.
- Food cart owners: I want you to find MY food cart and order lunch from ME! I have to have an account and log in.
- Administrator: I have total control over everything in the app. I definitely have to log in.
Spoiler alert: The “experiences” we wish to offer to each type of user suggests the need for distinct API bundles. On Apigee Edge, this means creating Products tailored to each user and offering those Products to registered App Developers. It could be some bundles are free to use, while others are monetized or require additional vetting.
The Developer Experience
We’re aware that the true consumers of our APIs are developers, not end users. So, we want a nice, intuitive, easily consumable API that developers will love!
There’s a lot of stuff written about RESTful API design. Apigee recommends building APIs that developers can understand and use very quickly. To us, that means picking URL patterns that are easy to grasp. Examples:
GET /carts
GET /carts/{cart_id}
GET /carts/{cart_id}/menus
POST /users/{user_id}/carts -d {“name”:”Better Burritos”, “city”:”Denver“}
PUT /users/{user_id}/carts/{cart_id} -d {“name”:”Best Burritos”, “city”:”Denver“}
It's interesting how much discussion we've had around choosing a pattern! Next week, we'll write about our finalized API design spec.
Managing and testing the APIs
Building an API is one thing; managing and testing it is another. We’re looking at using open source tools to move us down the road. We’re already using GitHub for source control. But we also want to automate certain tasks, so we’re looking at tools like Grunt, Maven, Yo, JSHint, Mocha, Jenkins, and others to help us manage and test our project code. This topic will make for some interesting future articles and practical applications of interest to the community.
Analyzing API use
Our very own Apigee docs state that “ Analytics is not an afterthought”! As the developers of an API program, we’re going to want to know:
- How to tell if the APIs are successful?
- How to measure adoption?
- How to tie API metrics to KPIs?
- How to structure the API program to facilitate adoption and maximize monetization?
We’ll explore Edge Analytics as well as analytics from Google and GitHub, and we will have lot’s of options to create custom reports and so on. We’ll also use Apigee API Health to keep tabs on the status and performance of our APIs.
Securing the APIs
OAuth, right? Done. Seriously, this is a big, fairly confusing and potentially scary topic.
We do plan to use OAuth 2.0 to secure certain resources, because the standard is well supported on Edge. We’re now thinking about which resource URIs should go in which Products. But, we’re not sure how to lock down both resource URIs AND verbs. (Products don’t specify anything about verbs). We’ve thought about using OAuth scopes, storing roles with users and checking the roles in conditional flows, using the old flow.resource.name trick, creating additional specialized Products, or, we’re not sure.
We also need to consider how to secure the actual data store, to prevent people from bypassing Edge altogether. We’ll explore security in depth in upcoming topics. We welcome any ideas you may have!
Implementing the API proxies
There’s a LOT under this category, but if we’ve done our up-front planning well, this part will be fun. First, we've already begun work on a mediation layer written in Node.js that allows Edge and BaaS to communicate. In theory, this BaaS mediator could be swapped out for one that communicates with a different data store without impacting the client-facing APIs. This seems like a good approach, and Edge's Node.js support makes it pretty easy to do.
We’ll also consider use cases and edge cases as we design the request and response flows through Edge, including which policies to use, and in which order. The short list of policies we'll be considering includes token generation, token validation, caching, rate limiting, stats collecting, kv maps, vault, threat protection, message logging, and, last but definitely not least, fault handling. This phase is where we’ll really get to eat our own DocFood!
Stay tuned for next week when we'll write about our API resource URI and Product designs.
