What is 'API first architecture' in modern web application

Question

I try to understand the API first architecture to apply on web application, and found out some info here, Advantages of a separate REST backend API?

Below I attach an example for better answer of the questions. I start using Angular.js for front-end. Node.js, Express.js for server.

folder structure

|-- server.js
|-- app
        |-- models
        |-- views
            |-- index.html
            |-- about.html
            |-- contact.html
        |-- controllers
            |-- app.js
|-- node-modules

app folder is a MVC structure for angular app. All of the POST GET PUT DELETE, MongoDB, Redis connection are in server.js. But when the server file get bigger, what is the best way to organize those business logic?

There is no view engine set on server.js. If I create "routes" folder in express, is this actual carry out an API first concept? Let's say, when user clicks a button to submit a form from browser directly, in this case, is server responsible for presentation layer?

index.html

 <form method='POST' action='/register'>
     // some code here..
    <button type='submit'>submit</button></form>

server.js

var rootPath = './app/views' 
router.post('/register' (req, res) =>{
  // some code here...
res.sendFile( rootPath + 'index.html');
}); 

Thanks in advance.

Answer 1

The API-first architecture means that you design the interfaces between your backend and frontend first, without focusing on the actual frontend implementation. It will make it easier to add new clients to your API in the future. For some good intro see:

• http://www.api-first.com/
• https://www.programmableweb.com/api-university/understanding-api-first-design
• https://medium.com/adobe-io/three-principles-of-api-first-design-fa6666d9f694
• https://dzone.com/articles/an-api-first-development-approach-1

In a web context it is usually done with single-page applications (SPAs) with RESTful APIs passing all data as JSON, with no HTML generated on the backend.

If you want to make a modern single-page application then you usually serve the same HTML file for every request to the frontend, so e.g. when user clicks any of those links the same HTML should be returned:

• http://www.example.com/
• http://www.example.com/some/page
• http://www.example.com/some/other/page

What is tricky here is that you need to make sure that you don't server that HTML for other assets like styles or images, so usually you serve it for missing files. Eg. when user wants to get /css/style.css then you serve the actual CSS but when user wants to get /a/b/c that doesn't exist then you serve the /index.html

So the frontend files - HTML, CSS, client-side JavaScript, images etc. are always static in a sense that the server always sends the same content to the client. Those could be sent by the same server as your API or a different server, on the same or on a different domain (but make sure to handle CORS correctly when you use different domains for the frontend assets and the backend API).

Now, all of the interaction of the frontend with the backend is done without reloading the page - so you don't serve HTML on the server as a response to form submits. You usually serve JSON data or (less commonly) XML instead of HTML.

For example your router.post('/register') handler could respond with something like res.json({ some: { object: 'example' } }); inested of sending HTML.

This is how it's usually done - you separate the frontend from the backend with a clear boundary of a well defined API and don't reload the HTML web page once it's loaded.

Search for more info on SPA, REST, JSON, XML, AJAX, GraphQL for more info.