API First, Mobile-First, Design First… How do I know where to start?

Dear Geek,

 

There have been a lot of “First” methodologies thrown around in the past few years: Mobile-First, Code-First, API-First, API-Design-First, Test-First, Contract-First, Model-First, Security-First, Design-First, and many more. Before I throw all these out the window and just start building something, can you tell me which “First” is the one I should be using?

 

—   FRUSTRATED WITH FIRSTS

Dear Frustrated,

I understand your frustration and I have some good news and bad news.

Bad News First (First joke!)

• Stick around another 5-10 years and there will be plenty more firsts to add to your collection!
• Definitions of these Firsts can vary from expert to expert.
• You cannot just pick a single first and run with it. No first is an island. You will probably end up using a lot of these…

Good News

While there are a lot of different “first” methodologies out there, some are very similar and have just matured just as our technology stack has.

Here is the first stack I recommend looking at when you are starting a new project:

1. Design-First (Big Picture)

Know the high-level, big-picture view of what you are building. Define the problem you are solving and the requirements to solve it. Are you going to need a Mobile app? Website? Something else?

Have the foresight to realize that whatever you think you will need, it will change in the future. I am not saying design for every possible outcome but use wisdom and listen to your experts.

2. API First

API First means you think of APIs as being in the center of your little universe. APIs run the world and they are the core to every (well, almost every) technical product you put on a user’s phone, computer, watch, tv, etc. If you break this first, you will find yourself in a world of hurt.

Part of this First is the knowledge that you better focus on your API first, before you start looking at your web page, mobile app, etc. If you try to build your mobile app first and then go back and try to create an API that matches the particular needs of that one app, the above world of hurt applies.

Not only this but having a working API will make design/implementation of your mobile app or website MUCH easier!

Another important point to remember. There will most likely be another client that needs what this API is handing out so take that into consideration as well.

3. API Design First and Code-First

I’ve grouped these next two together. Now I know I am going to take a lot of flak for this but hear me out.

Code-First

I agree that you should always design your API first and not just dig into building it, However, code is a legitimate design tool, in the right hands. Not everyone wants to use some WYSIWYG tool that may or may not take add eons to your learning curve and timetable. Good Architects (and I mean GOOD!) can design out an API in a fraction of the time it takes to use some API design tools. I am NOT saying everyone should do this but don’t rule out  Code-First because it has the word “Code” in it.

You have to know where to stop though.

Designing your API with code means you are doing design-only. You still have to work with the technical and non-technical members of your team to ensure that your API solves your business problem and is the best solution. If you can’t translate your code-design into some visual format that everyone can see and understand, DON’T use code.

API Design First

This is really a superset of Code-First design since the deliverable is an API design. A lot of people see this as the methodology that uses a GUI tool to generate a Swagger or OAS3 document. Just remember that this may not be the only tool in your tool belt. Look at what you and your organization NEED as a deliverable for API Design and take that into consideration before you pick your tool and start running with it.

4. Mobile-First (part one)

Wait?!? We shouldn’t be talking about Mobile-First yet!

Well, not fully, but there is a portion of Mobile-First you need to think about while you are in your API Design phase. Mobile devices and apps have a particular set of features and requirements that did not exist when we lived in a web-only world. It is important to take these in consideration so you don’t find yourself going back and having to rewrite a chunk of your API. Some of these features include latency, payload size, statelessness, push notifications, and security. Which leads me to my next first: Security-First.

5. Security-First

Security is absolutely key to the success (or failure) of an application or API. At this state, you will have to make decisions about how you want to secure your API and system.

Note: This does NOT mean that you have to integrate every aspect of the authentication/authorization security into the code of your API. A better decision might be to have that handled by your API Management or Service Mesh solution.

If you do need to integrate security into your API, try not to write your own security and use trusted and tested libraries in your API.

6. Contract-First

Your API is often referred to as the “contract” between your backend datasource (or datasources) and the consumers of your APIs (mobile, web, etc). If you have already done your API design and have solidified your interface (or contract), you might create a mock API that provides data that matches this contract. This will give you something to start working with on the next step: Mobile-First

7. Design-First (API Client)

This edition of  Design-First is brought to you in part by your Designer (whether in-house or outsourced). Have some good mockups and visual designs that you can get approval on BEFORE you start coding away at the app or website.

One caveat to this goes back to Code-First. Don’t eliminate code as a design tool. This is especially useful for teams that don’t have a dedicated graphic designer or when similar screens have already been designed and used in other apps or websites. As with the other Code-First, be sure you can present this in the visual manner needed to get approval from the team.

8. Mobile-First (part two)

Mobile-First at this stage does not mean you build your mobile app first but that you take mobile into consideration before building ANY clients for your API. Basically, if you need a website, build it with mobile in mind first. Don’t add mobile support to your website later.

And now for the rest of it…

Now that you have gotten through all the Firsts you can start working on your seconds, thirds, fourths, and fifths!

    Ask-a-Geek questions are answered by Brenton House, 
    an API and Mobile Geek who has been working in the
    development community for 25+ years.