API Directory Structure: a few different options
Published: 2024-03-29 03:01:44

The speaker discusses two main approaches to structuring API directories: one based on UI actions and the other based on services. In the UI action approach, APIs are organized according to user interface interactions, with each action potentially requiring a different number of API implementations. Conversely, the services approach categorizes APIs by the underlying services they support, with each service requiring a specific set of APIs. Both methods have their pros and cons, with the UI action approach facilitating communication between UI and API teams but potentially becoming complex as the UI evolves, while the services approach offers more flexibility for accommodating new services across various client platforms. The speaker suggests that a combination of these approaches may be beneficial, depending on the specific requirements of the project.

### Summary

**Introduction to API Directory Structuring:**
- Explanation of the importance of structuring API directories.
- Mentioning various options available for structuring.

**Option 1: Structuring by UI Action:**
- Description of structuring APIs based on user interface actions.
- Illustration of how API directories could be organized according to UI actions.
- Discussion on the number of APIs required for different UI actions.

**Option 2: Structuring by Services:**
- Explanation of structuring APIs based on services.
- Example demonstrating organizing APIs by different services.
- Comparison with UI action-based structuring.

**Pros and Cons of Each Approach:**
- Discussion on the advantages and disadvantages of structuring by UI action.
- Explanation of the benefits and limitations of structuring by services.
- Suggestion of using a combination of both approaches.

**Considerations for Implementation:**
- Discussion on considerations for choosing between UI action and service-based structuring.
- Mention of scenarios where each approach is more suitable.

**Personal Experience at Snowpal:**
- Mention of utilizing a combination of directory structures at Snowpal.
- Brief insight into how different structures serve different needs over time.

### Podcast

Check out on [Spotify](https://open.spotify.com/episode/4YG2Jowa75rLqzDbCEBjdA?go=1&sp_cid=03ae2ae7-c61c-4a5f-931b-46bad2d36df1&utm_source=embed_player_p&utm_medium=desktop).

### Transcript

**0:00**

Hey there, let's see how we can structure API directories. There's obviously many ways you could do this, but let's talk about a couple of options. Let me draw two options here and let's see what the differences are. The first option, you could do it based on UI action.

**0:20**

Let's see, you're building a user interface. It doesn't matter whether it's a mobile app or a web app. If there's a particular user action, then you can actually have your API is structured by the user actions. So in this case, the first UI action requires that you implement 3 APIs and the second UI action might require that you implement 4 APIs, while the third UI action might only require a single API implementation.

**0:46**

So that's one way to structure your API directories. The 2nd way you can do it is by your services, right? So there is a service one and then there is a service two and then there is a service 3. So whatever these services are, you can structure your APIs by the actual services.

**1:09**

So in this case, the first service requires 3 APIs to be implemented, the second one requires 4, and the third one might require three as well, right? So there's two ways you could go about from an API platform or API dev environment, whatever you want to call it.

**1:25**

Structuring standpoint, Each of them has a set of pros and cons. As just like everything else in life, if you do it by UI action, then as you're implementing new UI actions, whether it's pages or if you broke a single page down into multiple actions, you can actually create this or update the API documentation as a UI team if you wanted to and pass it along to the API team or push it to that documentation repo.

**1:52**

So the API team now knows what to implement and they'll go about their job of implementing these APIs so that it makes that communication a little bit easier if you looked at your implementation and your feature sets as mainly being driven by UI actions.

**2:10**

But that's and you can use a combination of these. They're not mutually exclusive, but you also may want to consider implementing API. Structuring them by services because you might be implementing a brand new API, brand new service within an API, and maybe that serves both mobile and web apps right?

**2:29**

Or multiple clients. In that case, doing it by UI action may not necessarily work because the UI action generally tends to be pretty specific to a client or a group of clients, whereas the services are very generic, they can be applicable to any number of N number of clients.

**2:47**

So if you structure the APIs by structure them by services, it'll actually help in that fashion, meaning you not know all the APIs that a particular service comprises of. We at snowpal.com we have hundreds of endpoints and we have a combination of these directory structures.

**3:08**

Each one plays a role at different at a specific point of time. But these are two ways at least two ways of doing this, option one and then option two. Let me know how you structure your APIs.

Thank you.