Why Does Front‑End/Back‑End Separation Increase Pain? Solutions with Raml‑Mocker

Why Front‑End/Back‑End Separation Increases Pain?

Front‑end/Back‑end separation is common, but after true separation many problems appear.

Why APIs change frequently?

Initial design was not well thought out, requiring better requirement understanding and interface design.

Low cost of change encourages frequent modifications.

A German proverb says you must spit into the soup to make people stop drinking it; similarly, informal verbal notifications of API changes lead to frequent rework and waste.

Why API documentation is always wrong?

Documentation is written when defining the API, but frequent changes make it lag behind; maintaining docs costs effort without value unless the API is public.

Why testing only starts near release?

A typical schedule: backend 4 days, frontend 4 days, integration 4 days, leaving only 2 days or less for testing, which forces bugs into production.

During development, testers cannot intervene because APIs and front‑end code keep changing; testing often starts only after "hand‑off" and becomes rushed.

How to solve?

Make API documentation valuable, increase the cost of changing interfaces, and involve testing early.

Treat the API spec as a contract that cannot be changed without agreement; front‑end developers, who understand the data needs, should drive the contract.

After the contract is set, generate a Mock Server; front‑end and test teams can develop against it while the back‑end evolves.

raml-mocker

raml-mocker ( https://github.com/xbl/raml-mocker ) is a Node.js mock server tool based on Raml. By adding example to a response, raml-mocker returns the mock data.

Getting Started

git clone https://github.com/xbl/raml-mocker-starter.git raml-api
cd raml-api
git remote rm origin

Install

yarn # or npm install

Start mock server

yarn start # or npm start

Test

curl -i http://localhost:3000/api/v1/users/1/books/ # or curl -i http://localhost:3000/api/v1/users/1/books/1

Generate API documentation

yarn run build # or npm run build

This uses raml2html to produce visual docs.

Configuration (.raml-config.json)

{
  "controller": "./controller",
  "raml": "./raml",
  "main": "api.raml",
  "port": 3000,
  "plugins": []
}

controller: path to controller directory

raml: path to Raml files

main: entry Raml file

port: mock server port

plugins: optional plugins

Mock Server Basics

Define example in the Raml response:

/books:
  /:id:
    post:
      body:
        application/json:
          type: abc
      responses:
        200:
          body:
            application/json:
              type: song # returned mock data
          example: !include ./books_200.json

books_200.json

{
  "code": 200,
  "data": [
    {"id": 1, "title": "books title", "description": "books desccription1"},
    {"id": 2, "title": "books title", "description": "books desccription2"}
  ]
}

Request with curl:

curl -i http://localhost:3000/api/v1/users/1/books

The mock data is returned; dynamic data per parameter requires advanced features.

Advanced: Dynamic Server

Add a (controller) directive in Raml to invoke custom logic:

/books:
  type:
    resourceList:
  get:
    description: Get user books
    (controller): user#getBook
    responses:
      200:
        body:
          application/json:
            type: song[]
            example: !include ./books_200.json

Corresponding controller (controller/user.js):

exports.getBook = (req, res, webApi) => {
  console.log(webApi);
  res.send('Hello World!');
};

raml-mocker runs on Express, so req and res follow Express conventions. webApi contains the request configuration.

Plugins

Plugins can process responses without a controller, e.g., using Mockjs:

var { mock } = require('mockjs');
module.exports = (body) => {
  try { return mock(JSON.parse(body)); } catch (e) {}
  return body;
};

Enjoy it!

Summary

Front‑end/back‑end separation clarifies responsibilities and can improve efficiency, but without a well‑planned workflow the benefits are lost, leading to waste. raml-mocker helps solve part of the problem by providing contract‑driven mock servers, while a unified team mindset is essential for rapid delivery.