Aha! moments are the best. Don’t you agree? Whether it’s learning something brand new or something I didn’t know quite as well as I thought, I live for the moments when things just click.
These moments are, of course, preceded by another kind of moment: the tilt-your-head, furrow-your-brows, something’s-not-right-here moment. I recently had one of those moments reading about API endpoints and resources.
Let me back up a minute. I’ve been learning about APIs and API documentation for the last several months. In addition to a lot of reading, I’ve taken Peter Gruenbaum’s Udemy JSON/XML for Writers and REST for Writers classes, and I’m currently in the middle of Tom Johnson’s API Documentation Course for REST APIs. I have learned a lot and recommend both the Udemy classes and Tom Johnson’s (free) course. (The hands-on activities for using APIs as well as documenting APIs are particularly helpful.)
Where’s the confusion?
After all I have learned, it was with some consternation that I got halfway through Tom Johnson’s lesson on documenting resource descriptions and realized I was confused about endpoints and resources. I thought I understood the concepts, but something I was reading didn’t quite fit. His example (halfway down this page) involves users and specific users, rewards and specific rewards, and missions. I’m sure some of my confusion arose because the example was more complex (i.e., more real life) than I had seen before. (Yay!) But also, I’m a very literal person, especially when I’m learning something new. I wondered: Is an endpoint the URL, or is a description of the URL the endpoint? And something I hadn’t thought of before: can an endpoint relate to more than one resource?
Models to the rescue
When I get confused, I naturally turn to some type of visual model to help me understand. Below are the models I created. DISCLAIMER: I’m not sure these are 100% correct, but (for right now) they make sense to me. (Worst case scenario, they make my understanding visible so it will be easier to correct any errors.)
First: A Venn diagram showing the resources and their relationship to each other, along with generalized descriptions of the endpoints.
Next: Addition of specific endpoints and two examples of endpoint paths (URLs).
Finally: A table that shows all relationships between resources and endpoint examples, including all endpoint paths.
After creating the Venn diagrams and table, I’ve decided that (1) the users, rewards, and missions are the resources, (2) yes, an endpoint can relate to more than one resource, and (3) endpoints can be described using either a description or a full or partial URL. (However, I like the distinction of endpoint path for the URL and endpoint for the description, so that’s what I used in my models.)
Now that I’ve gone through this process, I’m not sure why I was so confused. But that’s the way it always is, right? Once you figure it out, it’s easy.
Unless, of course, I don’t really understand as well as I think I do.
Update: After continuing with the API Documentation Course, I realized I needed to update the diagrams to reflect alternative nomenclature for Resources and Endpoints. Specifically, that Resources are sometimes called Objects, and that Endpoints are sometimes called Methods. See the comments section for additional clarification. Nov 18, 2015.
5 thoughts on “API Endpoints vs Resources”
Hi Gale, thanks for the writeup. I like your diagram. Yes, you’re thoughts are right on target here. I also like your distinction between endpoints and endpoint paths.
One note. As you browse different API doc sites, you’ll find that the nomenclature differs considerably, and there are no real standards. What one site refers to as a resource, another calls an object. What one site refers to as endpoints, another calls methods. And since APIs themselves differ greatly in structure and function, the docs differ in their descriptions.
For example, if an API really just has 1 resource with 5 different endpoints, it might not make sense to even talk about the resource as a distinct entity. Conversely, if an API has distinct resources and lots of different endpoints for each resource, they may use different terminology to describe it all.
All I’m really saying is that it’s nonstandard territory here.
Good timing! Just before reading your comment I had changed my table to say Resources/Objects and Endpoints/Methods after reading your Box API example! I’ll update the post shortly.
Thanks for the examples in your comment, they help a lot. I’ll be prepared to adjust my understanding as I encounter changing terminology and special circumstances of other, different APIs.
nice diagrams – I also find that visuals help me to think through problems. :)
Now waiting to start on a small contract restructuring API documentation job I’m also planning to follow Tom’s course and the Udemy courses you mentioned.
Hi Ben, you might also check out Write the Docs. They have conferences in the US and Europe as well as local meetups. I just went to an API meetup last week in Redwood City, CA which was very helpful. It’s also a good way to meet people and make connections. Good luck!