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.

Background

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.

In conclusion

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.