Technology Planning: API First Design

How to structure teams for API first development isn't as complicated as you might think.

Are you running a tech organization that is just starting out or on the verge of heavy growth? Listen up. 

“Microservices”, “API First”, “Service Driven Architecture”, or any other trendy topic that you hear about like these may seem like buzz but if you understand the true nature of these methodologies, it could mean the difference between rapid growth or being bogged down in ten years of technical debt. 

First, you have to understand that applications (at a high level) are comprised of just 2 aspects:

• User Experience (Developer or Consumer)
• Contracts: A series of questions and answers that powers the flow of information from the producer and consumer.

How can application development be that simple? Truth be told, it isn’t, but the concept is. For sake of brevity, I will forgo discussions around security and governance and focus solely on the general concepts. Maybe I will write an article later on those. Im also going to skip over User Experience (UX) for this article even though I consider that a critical item for success.

Contracts

I’ve been saying for years that applications start and end with analytics. It’s like “bookends”. You set up to collect information, design and build your application(s) around those metrics and then review the data to determine what is next.

It starts with designing your database to support your workflows. Many times, the biggest technical mistake companies make is they build their application around the database. I refer to this as “programmatic database development”. Not saying there isn’t a time and place for it but one thing I have come to learn about application development in the enterprise space is that your databases should be dumb. Neither your services or your data architecture should know about each other. 

This is where the contract designs are critical. Your application should ask an expected question (format) and get an expected answer (format). Where artificial intelligence comes in (much larger topic) is the ability to add deductive reasoning to the question. A simple REST example is getting someone’s name.

Application: What is your name? (First, Last) 

User: John Smith

Service: POST https://domain.com/input/name text=John Smith

Response: GET https://domain.com/output/name fullname=John Smith; firstname=John; Options=[Yes,No]

Application: Hey John Smith, thank you for telling me your name. Can I call you John? (Yes/No)

User: Yes

Great? Well, its exact question and answer specific. My application is expecting the user to ask the question in a very specific way and I will respond in kind. This happens everywhere within the application environment and as such, can be tested easily. Everything from what content to show to how to deliver that content is driven from these responses. 

Pro tip: Have a mock API framework so your front end teams are not waiting on your back end teams.

If you design out your APIs and focus a team to develop those contracts, you will have way more success than building them ad hoc. Whenever possible, this is how my teams are structured. Service teams and implementation teams. 

Treat Implementation Teams As Vendors

If the goal is API first development, your implementation teams need to immediately be treated as a vendor. This will create best practices within your service teams. Things like documentation, registration, versioning, deprecation, communication and design patterns become required. A service is only successful if someone can implement without platform knowledge. Start with this mindset and then UX will drive service offerings as a request. 

This also makes it easier to create an open network for others to leverage your platform. It is so much easier for sales teams to sell your services to businesses when you don’t have to hack solutions together. Remember, every hack has to be supported and some companies spend up to 75% of their time managing one-off platform connections. You can’t scale in that model.

If you have questions, please reach out to me at [email protected]. Would love to discuss your challenges to see if I can help.

Article: https://johnsteinmetz.net/technology-planning-api-first-design/