API Directory Structure: a few different options
How you define your API Directory Structure will make a ton of difference to your API Development productivity. We tried various approaches before arriving at the current one that works best for us.
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
Topic: API directory structuring.
Content Overview:
Discusses two main options for structuring API directories:
By UI action.
By services.
Explains the differences between the two approaches.
Highlights pros and cons of each approach.
Mentions the potential use of a combination of both approaches.
Provides insights based on the speaker's experience at snowpal.com.
Key Points:
Structuring APIs by UI action vs. by services.
Considerations for ease of communication and implementation.
Flexibility and applicability to different types of clients.
Purpose: To provide guidance and insights into different methods of organizing API directories effectively.
Audience: Likely targeted towards developers, API architects, or individuals involved in API design and development.
Length: Approximately 3 minutes and 8 seconds.
Style: Informative and instructional, with a mix of explanation, examples, and personal insights.
Delivery: Appears to be a spoken presentation or discussion, possibly from a tutorial, meeting, or instructional video.
Conclusion: The speaker invites feedback and discussion on how others structure their APIs, indicating an openness to further dialogue or exchange of ideas.
Podcast
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.
Snowpal Products
Backends as Services on AWS Marketplace
Mobile Apps on App Store and Play Store
Education Platform for Learners and Course Creators