apimd

apimd lets you to write APIs in Markdown and use them as mocks.

## GET /api/site
 
White label site branding and navigation? I have a bad feeling about this.
 
```yaml
branding:
  title: "Fortune Wookie"
  imageUrl: "/logo.svg"
navigation:
  title: "Site"
  items:
    - title: "Home"
      pageUrl: "/"
    - title: "Darth Later"
      pageUrl: "/going-out"
    - title: "Ellie Vader"
      pageUrl: "/going-up"
```
 
## POST /api/login
 
### Request
 
It's an older login, server, but it checks out.
 
```yaml
username: "[e-mail]"
password: "j0nes"
```
 
### Response
 
We're fine. We're all fine here, now, thank you.
 
```yaml
token: "THX1138"
user:
- givenName: "Indiana"
- familyName: "Solo"
```
 
### Response 401
 
I find your lack of authentication disturbing.
 
```yaml
error: "Missing {username,password} request body"
```
 
## GET /api/is-logged-in
 
### Request Headers
 
```yaml
x-session-id: "THX1138"
```
 
### Response Body
 
Do...
 
```yaml
success: true
```
 
### Response Body
 
Or do not...
 
```yaml
success: false
```

Based on the example, a GET request to /api/site returns the following json:

{
  "branding": {
    "title": "Fortune Wookie",
    "imageUrl": "/logo.svg"
  },
  "navigation": {
    "title": "Site",
    "items": [
      {
        "title": "Home",
        "pageUrl": "/"
      },
      {
        "title": "Darth Later",
        "pageUrl": "/going-out"
      },
      {
        "title": "Ellie Vader",
        "pageUrl": "/going-up"
      }
    ]
  }
}

A POST request to /api/login returns the following 401 json:

{
  "error": "Missing {username,password} request body"
}

However, adding a request body of {"username":"[e-mail]","password":"j0nes"} returns the following json:

{
  "token": "THX1138",
  "user": [
    {
      "givenName": "Indiana"
    },
    {
      "familyName": "Solo"
    }
  ]
}

Also, a POST request to /api/is-logged-in returns the following json:

{
  "success": false
}

While adding a x-session-id header of THX1138 returns the following json:

{
  "success": true
}

It is neat how JSON and YAML formats are supported, and JavaScript as well:

export default fetch(
  'https://api.openbrewerydb.org/breweries',
  { type: 'json' }
).then(
  breweries => breweries.map(
    brewery => ({
      patchedAPI: 'patched',
      ...brewery
    })
  )
)

Have fun!

---

Installation

npm install apimd

Usage with Markdown

const parse = require('apimd/parse')
 
parse(MARKDOWN_STRING)

Usage with Express

// server.js
const express = require('express')
const apimd = require('apimd/middleware')
 
app.use(apimd(/* options */))

Usage with Rescripts

// .rescriptsrc.js
module.exports = [
  ['apimd/rescript']
]

Usage with Create React App Rewired

Add apimd to config-overrides.js in your React app directory:

// config-overrides.js
const apimd = require('apimd/rewired')
 
module.exports = {
  devServer: apimd(/* options [, function devServer(configFunction) {}] */)
}

Options

The following default options may be configured:

{
  "fallbackBody": {},
  "fallbackHeaders": {},
  "fallbackStatus": 401,
  "jsonReplacer": null,
  "jsonSpace": "  ",
  "live": false,
  "src": "api.md"
}

Note: In the rescript and rewired versions, src is "src/api.md" and live is true.

Configuration with package.json

The rescript and rewired versions of apimd may also be configured from package.json:

{
  "apimd": {
    "live": false
  }
}