Skip to content

📡 API

Jump to bottom
Ringo Hoffmann edited this page Jan 4, 2022 · 2 revisions

snippets is accessed via a HTTP REST API.

Models

User

A user object.

{
  "username": "zekro",
  "id": "5189b770-3c49-45a8-8ebc-f6d40772c371",
  "timestamp": "2021-05-10T14:39:17.033443+00:00"
}

UserCreate

An extended User object containing a masterkey property returned on user creation.

{
  "username": "zekro",
  "id": "5189b770-3c49-45a8-8ebc-f6d40772c371",
  "timestamp": "2021-05-10T14:39:17.033443+00:00",
  "masterkey": "..."
}

TokenResponse

Response object when exchanging a masterkey against the API.

{
  "token": "..."
}

Snippet

A code snippet object.

{
  "ident": "slUkuX",
  "language": "golang",
  "code": "package main\n\nimport ...",
  "owner": {
    "username": "zekro",
    "id": "5189b770-3c49-45a8-8ebc-f6d40772c371",
    "timestamp": "2021-05-10T14:39:17.033443+00:00"
  },
  "id": "afb8d6a3-0484-468e-85c3-b3c3938609e4",
  "timestamp": "2021-05-30T14:23:22.978033+00:00"
}

Endpoints

PUT /users/:username

Create a new user with the given username.

Example:

> GET /users/zekro HTTP/2

The response of this request will look like following:

{
  "username": "zekro",
  "masterkey": "W8aoXaBtnYIS79sFtyuPfudYnBxR5bTKM9huATRNkqsO7dOj-WZa0ezk7SmypIaC3WjmtGXSdfJe56ymzNJUKmPNunIdB8ma-xubWfSbEErpyH7uEYZnn-uqK9cgNGKOF1QbqwfqK9ouCETJjvy99sOFKRTo1akc74n8HGP/7Pc_",
  "id": "66685ee3-4886-47fc-93d2-38ed1eaecaf2",
  "timestamp": "2022-01-04T10:50:10.9548948+00:00"
}

⚠️ ATTENTION
The returned masterkey will never be returned from the API after initial account creation, so store it securely!

POST /users/:username/apitoken

Exchange a masterkey to retrieve an apikey, which then must be used to authenticate requests against the API. The token has to be passed in the Authorization header using the bearer token type.

Example:

> POST /users/zekro/apitoken HTTP/2
> Authorization: bearer W8aoXaBtnYIS79sFtyuPfudYnBxR5bTKM9huATRNkqsO7dOj-WZa0ezk7SmypIaC3WjmtGXSdfJe56ymzNJUKmPNunIdB8ma-xubWfSbEErpyH7uEYZnn-uqK9cgNGKOF1QbqwfqK9ouCETJjvy99sOFKRTo1akc74n8HGP/7Pc_

The response of this request will look like following:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI3MWRlYTZiYi05NWU5LTRkN2MtOTRhZi05ODZjNzFkOWQ4YjIiLCJ1bmlxdWVfbmFtZSI6Inpla3JvZGV2ZWxvcG1lbnQiLCJuYmYiOjE2NDEyOTQxMzYsImV4cCI6MTY3MjgzMDEzNiwiaWF0IjoxNjQxMjk0MTM2LCJpc3MiOiJyYW5uYS1zbmlwcGV0cyJ9.-JN5evO0O7RjMUumYclA909B8wHYn38OfX39MAn1_U0"
}

DELETE /users/:username

Delete a user account. This requires authentication using the masterkey passed as basic token via the Authorization header.

Example:

> DELETE /users/zekro HTTP/2
> Authorization: bearer W8aoXaBtnYIS79sFtyuPfudYnBxR5bTKM9huATRNkqsO7dOj-WZa0ezk7SmypIaC3WjmtGXSdfJe56ymzNJUKmPNunIdB8ma-xubWfSbEErpyH7uEYZnn-uqK9cgNGKOF1QbqwfqK9ouCETJjvy99sOFKRTo1akc74n8HGP/7Pc_

The response of this request will look like following:

204 No Content

POST /snippets

Create a new snippet.

ℹ️ Info
The created snippet will be linked to the authenticated account. This also allows alternation and deletion by the authenticated user. A snippet can also be created anonymously.

Example:

> POST /snippets HTTP/2
> Content-Type: application/json
> Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI3MWRlYTZiYi05NWU5LTRkN2MtOTRhZi05ODZjNzFkOWQ4YjIiLCJ1bmlxdWVfbmFtZSI6Inpla3JvZGV2ZWxvcG1lbnQiLCJuYmYiOjE2NDEyOTQxMzYsImV4cCI6MTY3MjgzMDEzNiwiaWF0IjoxNjQxMjk0MTM2LCJpc3MiOiJyYW5uYS1zbmlwcGV0cyJ9.-JN5evO0O7RjMUumYclA909B8wHYn38OfX39MAn1_U0

{
  "code": "package main\n\nfunc main() {\n\tprintln(\"Hello world!\")\n}",
  "language": "go"
}

The response of this request will look like following:

{
  "id": "7ed9ec0c-76a8-40d0-bebf-e99c6af1bf87",
  "ident": "aaQ0KR",
  "language": "go",
  "code": "package main\n\nfunc main() {\n\tprintln(\"Hello world!\")\n}",
  "timestamp": "2022-01-04T11:40:23.8534821+00:00",
  "owner": {
    "username": "zekro",
    "id": "66685ee3-4886-47fc-93d2-38ed1eaecaf2",
    "timestamp": "2021-05-10T14:39:17.033443+00:00"
  }
}

GET /snippets/:ident

Get a snippet object by its ident or id.

Example:

> GET /snippets/aaQ0KR HTTP/2

The response of this request will look like following:

{
  "id": "7ed9ec0c-76a8-40d0-bebf-e99c6af1bf87",
  "ident": "aaQ0KR",
  "language": "go",
  "code": "package main\n\nfunc main() {\n\tprintln(\"Hello world!\")\n}",
  "timestamp": "2022-01-04T11:40:23.8534821+00:00",
  "owner": {
    "username": "zekro",
    "id": "66685ee3-4886-47fc-93d2-38ed1eaecaf2",
    "timestamp": "2021-05-10T14:39:17.033443+00:00"
  }
}

GET /snippets

List all linked snippets of an authenticated user.

ℹ️ Info
The returned snippet objects do not contain the fields code and owner.

Example:

> GET /snippets HTTP/2
> Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI3MWRlYTZiYi05NWU5LTRkN2MtOTRhZi05ODZjNzFkOWQ4YjIiLCJ1bmlxdWVfbmFtZSI6Inpla3JvZGV2ZWxvcG1lbnQiLCJuYmYiOjE2NDEyOTQxMzYsImV4cCI6MTY3MjgzMDEzNiwiaWF0IjoxNjQxMjk0MTM2LCJpc3MiOiJyYW5uYS1zbmlwcGV0cyJ9.-JN5evO0O7RjMUumYclA909B8wHYn38OfX39MAn1_U0

The response of this request will look like following:

[
  {
    "id": "7ed9ec0c-76a8-40d0-bebf-e99c6af1bf87",
    "ident": "aaQ0KR",
    "language": "go",
    "timestamp": "2022-01-04T11:40:23.8534821+00:00"
  }
]

DELETE /snippets/:ident

Delete a snippet which is linked to a user by its ident or id.

Example:

> DELETE /snippets/aaQ0KR HTTP/2
> Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiI3MWRlYTZiYi05NWU5LTRkN2MtOTRhZi05ODZjNzFkOWQ4YjIiLCJ1bmlxdWVfbmFtZSI6Inpla3JvZGV2ZWxvcG1lbnQiLCJuYmYiOjE2NDEyOTQxMzYsImV4cCI6MTY3MjgzMDEzNiwiaWF0IjoxNjQxMjk0MTM2LCJpc3MiOiJyYW5uYS1zbmlwcGV0cyJ9.-JN5evO0O7RjMUumYclA909B8wHYn38OfX39MAn1_U0

The response of this request will look like following:

204 No Content
Clone this wiki locally