Example API

A schema for a small example API.

• App
  • POST /apps
  • DELETE /apps/:id
  • GET /apps/:id
  • GET /apps
  • PATCH /apps/:id
  • POST /apps/:id/files
• Recipe
  • GET /recipes
• User

App

An app is a program to be deployed.

Properties

• id
  • unique identifier of app
  • Example: "01234567-89ab-cdef-0123-456789abcdef"
  • Type: string
  • Format: uuid
  • ReadOnly: true
• name
  • unique name of app
  • Example: "example"
  • Type: string
  • Pattern: /^[a-z][a-z0-9-]{3,50}$/
• private
  • true if this resource is private use
  • Example: false
  • Type: boolean
• deleted_at
  • When this resource was deleted at
  • Example: nil
  • Type: null
• user_ids
  • Type: array
• users
  • Type: array

POST /apps

Create a new app.

• name
  • unique name of app
  • Example: "example"
  • Type: string
  • Pattern: /^[a-z][a-z0-9-]{3,50}$/

POST /apps HTTP/1.1
Content-Type: application/json
Host: api.example.com

{
  "name": "example"
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "private": false,
  "deleted_at": null,
  "user_ids": [
    1
  ],
  "users": [
    {
      "name": "alice"
    }
  ]
}

DELETE /apps/:id

Delete an existing app.

DELETE /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Host: api.example.com

HTTP/1.1 204 No Content

GET /apps/:id

Info for existing app.

GET /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "private": false,
  "deleted_at": null,
  "user_ids": [
    1
  ],
  "users": [
    {
      "name": "alice"
    }
  ]
}

GET /apps

List existing apps.

GET /apps HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example",
    "private": false,
    "deleted_at": null,
    "user_ids": [
      1
    ],
    "users": [
      {
        "name": "alice"
      }
    ]
  }
]

PATCH /apps/:id

Update an existing app.

• name
  • unique name of app
  • Example: "example"
  • Type: string
  • Pattern: /^[a-z][a-z0-9-]{3,50}$/

PATCH /apps/01234567-89ab-cdef-0123-456789abcdef HTTP/1.1
Content-Type: application/json
Host: api.example.com

{
  "name": "example"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "private": false,
  "deleted_at": null,
  "user_ids": [
    1
  ],
  "users": [
    {
      "name": "alice"
    }
  ]
}

POST /apps/:id/files

Upload an attachment file for an app

• file
  • an attachment of app
  • Example: "... contents of file ..."
  • Type: string

POST /apps/01234567-89ab-cdef-0123-456789abcdef/files HTTP/1.1
Content-Type: multipart/form-data; boundary=---BoundaryX
Host: api.example.com

-----BoundaryX
Content-Disposition: form-data; name="[file]"

... contents of file ...

-----BoundaryX--

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "example",
  "private": false,
  "deleted_at": null,
  "user_ids": [
    1
  ],
  "users": [
    {
      "name": "alice"
    }
  ]
}

Recipe

Properties

• name
  • Example: "Sushi"
• user
  • Type: object

GET /recipes

List recipes

GET /recipes HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "Sushi",
    "user": {
      "name": "alice"
    }
  }
]

User

Properties

• name
  • Example: "alice"
  • Type: string