Why should API be First

This is a good questions. Why should I worry about API First? Why should it be a first class citizen in our architecture.  The reason is simple: You need to be able to respond to change quickly and rapidly develop new solutions to fix your problems.  With the other "first" approaches the process is very long because you are always creating custom stuff or having to weave together the APIs at the point of integration and the lack of consistency and versioning can lead to chaos.

We have all been on projects where the solution architecture was created and then someone said oh you need to provide blah data to this other system and oh there is another system that needs this other data often happening later in the project when resources are tight and you have to piece together an API quickly to solve the issue. In the worst case you may even have different people work on different parts of the API. Then when it comes time to work with these other applications that need your data, they look at your API and scratch their head. When do I need to pass the API an auth token and when is it an API Key and when do I pass a json and when do I pass a series of string parameters? Even stranger is when you have one API that is REST and returning XML and the other is JSON based.  I have seen that from the same vendor for the same application. It is scary.

For this reason, sitting down and designing a basic API framework from the start is important. Even if the API initially returns a small amount of data or maybe nothing at all, the basic mechanisms of authentication, how data is passed to the API, how it is returned, how the API is versioned is worked out. Then as you build out the API you add new interfaces or version interfaces that change still supporting the older ones.  This makes people integrating with you very happy.

Now back to the initial reason: "You need to be able to respond to change quickly and rapidly develop new solutions."  By making your API a first class citizen and documenting it well it means that someone building a new solution can quickly look at your documentation and determine which APIs they need to use and once they have used one API they will know how to work with others because of the consistent design.  If they need new functionality, you can extend the API for them without affecting other solutions.

Now this only happens with proper API design. In the next few articles we will describe some of the best practices that will help you do this.

Introducing Firsts for Solutions Architecture

There is a lot of talk about different firsts in the Solutions Architecture. When people say something is xyz First they mean that xyz is a first class citizen when you start the process of designing your architecture. You can only have 1 first class citizen but you can have many second class or third class.

Here are a few of examples of "firsts":

• Code First - This means you need to start coding first in C# or VB.NET and then EF will create the database from your code
  
• Model First - Best described in the article on the Model First Approach "In the Model-First approach, you create the entities, relationships, and inheritance hierarchies directly on the design surface of EDMX and then generate the database from your model."

• Database First - Best described in this article on the Database First Approach "The Database First Approach creates the entity framework from an existing database. We use all other functionalities, such as the model/database sync and the code generation, in the same way we used them in the Model First approach"

• Config First - This is the idea that you make your application flexible enough that you can extend it simply through configuration.  Salesforce was the first to introduce this with their No Code premise and it has led to much better solution implementations because you tweak a couple settings and a way you go. 

• Api First - This is the more modern approach and the one that will be discussed in this series of articles. The first place to start is reading this article on Principles of API First Design as we will be talking about this in the following few blog posts.

I will be adding more "Firsts" to this blog post later but the important thing is it gives you a taste for the different "first" approaches as you may use some of their concepts as "seconds" or "thirds".