The world of API-First has swept developer marketing by storm. With so much information scattered around the Internet — and managers inquiring about the — a lot of pressure is being applied to squeeze out a reasonable strategy. We're all familiar with that . Paraphrased: API-First roadmap Jeff Bezos memo API all the things or get pelted with rotten tomatoes. And now this mega-rich guy is . Clearly, it's time to get serious. A lot of us may be thinking, wow, okay, this memo came out in 2002. According to , a large number of professional developers were between the ages of 6 and 15 at this time. Y'all were playing with Bratz dolls or looking up GTA: Vice City cheat codes while APIs were being mandated from on high. Don't bring this up with your manager. taking William Shatner to space StackOverflow's 2021 Developer Survey Instead, communicate a strategy using these 5 tips! Know your Audience The first key step in any software project is to . These are the folks — both business and technical — who will set the game board, make the rules, and let you know if your team is actually winning. Once established, here is a sample of the questions to ask 🕵️: find the stakeholders What do we feel a successful API-first strategy enables? Which of those benefits is most impactful? What's motivating an API-first strategy ? today When business stakeholders answer questions, we do not interject with a correction we believe is more . Let's take this up with our developer compatriots when ironing out the details. This keeps us all out of trouble. 🙏 technically correct It may be too early to know in the beginning, but a question to plant in everyone's mind is: How do we measure success when moving to an API-first strategy? Let's not leave ourselves out of the equation! As members of the development team, our insight is important here, as well. Speak the language Sometimes, we just nod and smile when we don't understand each other. And maybe that's fine if we're video chatting during the awkward networking phase of our favorite virtual API conference. When it comes to building software, . finding a common vocabulary is a productivity hack In , this is known as the Ubiquitous Language. Domain experts know more about how the business functions, and this creates . Domain-Driven Design information asymmetry According to Eric Evans: Translation blunts communication and makes knowledge crunching anemic. When we're building APIs, we should be mindful of this common language. Should the property be called or ? state status Is it a or an ? soft_delete eviction Is it a or a ? retrospective harbinger_of_death As we go through this exercise, we will often run into undefined behavior. This is a great opportunity to work together and . Then we can effectively model those workarounds in the API. Beep boop. 🤖 discover if any exist in the business today shadow processes Understand the Building Blocks Distributed systems are hard. When we spend time weighing the options, we take a proactive approach to architecture. It takes a lot of practice before we can speed-run our way to victory. Single Page Apps (SPAs) and APIs are everywhere. They're the de facto standard for new applications. We could just slap together a quick API to turn SQL query results into a JSON payload. Ship it! 🙈 There are more than a couple of elephants hidden in this labyrinth. Which component owns ? application state What are the trade-offs related to ? storage, compute, and data transfer What are our API ? consumer use cases SPAs are in a client-server architecture. A common approach is to let the API act as a thin layer over data storage while moving compute to the Web browser and taking on more costs for data transfer. thick clients Thinking about our consumer use cases, we can make a decision on which properties and trade-offs make the most sense. Where we give control, we give complexity. If we want to delegate much of the control to the thick client, we can look at a solution like . The trade-off is pushing query and mutation decisions to every client application. If we want to centralize that complexity on the server-side, we can look at patterns such as . GraphQL materialized views Whatever decisions we make, let's make them deliberately. Documenting these motivations, system capabilities, and trade-offs can give us a cheat code for the next API-First project. And yes, by the time you're done reading this sentence, the documentation is already out of date. We're still working on that one. Plan for next steps Whew. We did it! Spot bonuses all around! jk jk... No matter how fast or slow we move when building software, one thing is always certain: we got it wrong. Either we missed a requirement, or the business needs to be changed, or legislation was introduced or... or... The list is never-ending. Some of us use humor as a defense mechanism. Here are a few ways we can protect our systems without therapy: What are our vectors? scalability Where can we find opportunities? performance How can our APIs ? evolve HTTP is the most successful protocol of its kind. Let's steal from it. Communications move through several network layers. We can take advantage of this, often transparently. are proxies that apply security, message transformation, custom routing, and more to centralize policy management. Use the network . API Gateways This isn't just part of a terrible whiteboard interview to optimize a search algorithm. HTTP allows caching at the client, the server, and intermediaries. Bust out that header! It's a quick performance win. Figure out a caching strategy . Cache-Control API evolution is a big topic. For now, it's good to remember that most JSON parsers are forgiving by default. . We can take advantage of this. There are also various deprecation signals to evaluate, such as the . It's easier to add a field than to remove one Sunset header Design with intention There's always room for exploration and improvement, so let's do it collaboratively. API definitions offer a great medium for discussion (not just automation). Rapid prototyping of APIs is only getting better. We can author an OpenAPI definition, generate a mock server, collaborate on design, and start the next iteration . all within the same tool Examples of Postman collections generated from API description formats: Generated from a GraphQL schema Generated from an OpenAPI definition Success emerges from a combination of many disciplines working together to solve problems and create opportunities. We should . Look to processes like: make intention explicit Event storming Value-stream mapping API Lifecycle Blueprints The term can have different meanings to different people. Don't go into the API-First strategy unarmed! To recap: API-First Know your audience. Speak the language. Understand the building blocks. Plan for next steps. Design with intention. Follow these 5 tips, and you'll be the next person to take a trip on that CEO's weird-looking rocket! 🚀✨ Also Published Here

Microsoft

Mozilla

Read more wacky API tomfoolery at swiber.dev!

2022 - HackerNoon Contributor of the Year - Api

2022 - HackerNoon Contributor of the Year - Cicd

2022 - HackerNoon Contributor of the Year - Kubernetes

2022 - HackerNoon Contributor of the Year - Software Architecture

Read my stories on HackerNoon

Learn APIs with Kevin @ swiber.dev

Subscribe to the swiber.dev Newsletter

Nominated for 2022 - HackerNoon Contributor of the Year - Api

Nominated for 2022 - HackerNoon Contributor of the Year - Software Architecture

Nominated for 2022 - HackerNoon Contributor of the Year - Kubernetes

Nominated for 2022 - HackerNoon Contributor of the Year - Cicd

Too Long; Didn't Read

Get free API security automated scan in minutes

Tips for Developers to Survive API-First

Tips for Developers to Survive API-First

Too Long; Didn't Read

Companies Mentioned

@kevinswiber

RELATED STORIES