Join Keith Casey for an in-depth discussion in this video Identifying participants, part of Designing RESTful APIs.
- In this video We're going to begin our API Modeling Process. No wait, let me correct that. We're not going to model the API quite yet. The first thing we need to do is have a clear understanding of our business process. If we don't know what that is, and what it accomplishes, we'll never be able to build an API to support it. This is the process we're going to be stepping through, and notice, Step 1 is Identifying the Participants. To put it simply, our participants are the ones who will be involved in the business process that eventually uses our API.
Actually, let me rephrase that. our participants are the entities who will be involved in the business process using the API. I say that specifically because, the various IOT devices, bots and monitoring services, we need to understand that not all of our participants are humans. From here forward, whenever I say participant, remember that I could mean a person, or an entity. Our first step of this is to figure out who is involved in our business process. This could be any entity, indirectly or directly, that takes action, or receives action, as a result of an event.
For each participant, we need to capture who they are. I'd go as far as giving them a name, so we're not just talking about a developer but developer Dan, or developer Diane. Next, we need to know if they are internal or external to our organization. Getting adoption of our API is probably easy if we're building it for another team at our company, but that still doesn't mean we can get sloppy. After all, some people on that team will have your boss's email address. Finally, we need to know whether they're active, taking an action, or passive, waiting for an action.
Let's take a simple scenario of ordering a cup of coffee at your local coffee shop. In this case, obviously we have you, and the barista who makes the coffee. Those are the easy ones, but quite often, there are multiple people working at the coffee shop where one takes the order, and the other takes the payment, while yet another makes it. So now we have three participants. But wait, did you pay with cash? Or a debit, or credit card? Maybe we have a payment processor in there. Are there other customers? Are their orders coming up before, or after ours? Are they participants too? This is starting to lead to one of the most dangerous problems involved in modeling any process; the boundaries.
If we're not careful, we could end up modeling inventory management systems for the cups, the coffee machine for the workflow, the payment processor and lots of other things. We must be careful here. In this case, let's keep it simple. Let's consider you, the cashier, and the barista. With the acknowledgment that the cashier and the barista could be the same person. In the next video, we're going to talk individual activities and who's involved in what.
- Approaches to adding an API
- Modeling tips
- Identifying activities and breaking them into steps
- Mapping activities to verbs and actions
- Creating and grouping API methods
- Validating your API
- HTTP headers and response codes
- Common design challenges
- Versioning best practices
- Hypermedia and documentation approaches