Let's Build an API together - Part 7

Last Update: 21.12.2017. By Jens in API Series | APIs | Newsletter

I was going to use API Blueprint for designing the API and later use tools for generating a Spring MVC endpoint with it. However, as I had a basic version of the API spec, I noticed that the tool would need to run in Javascript either by hand or as a task in the build tool Grunt. Image red lights and a nice beep now :-) it becomes complicated when using two build systems in one deliverable. Also, it’s a completely different tech stack and I sometimes have trouble with nodejs tools because yeah, js devs love living on the edge. Me not, I love stable techs as it saves me headaches.

What do we learn from my mistake?

Check those dependencies before you start. Better fail at the beginning than wasting days later in fixing things up.

I now move to RAML as there is a Maven plugin for generating Spring MVC code backed by a company. I wrote a short overview before as part of an API doc series. The tutorials for RAML are ok, and I think one can understand a RAML definition even without any knowledge of the syntax.

The description with the first endpoint looks:

#%RAML 1.0
---
title: Kanban API
baseUri: http://kanban.codeboje.de/{version}
version: v1
description: Basic version of the Kanban API

mediaType: application/json

types:
   Task:
     properties:
      id:
          description: "unique ID of a task"
          type: "string"
      content:
          description: "The actual task content aka description"
          type: "string"
      category:
          description: "category of the task"
          type: "string"
      lane:
          description: "The lane the task belongs to"
          type: "string"

/tasks:
  get:
    description: Retrieves all **tasks**
    responses:
      200:
        body:
          application/json:
            type: Task[]  
            example: | 
              [
               {
                 "id": "9781111",
                 "content": "How to ...",
                 "category": "cat1.",
                 "lane": "ready"
               }
              ]