Snippets

Snippets are at the core of CodeBottle, and so there's a bunch of end-points associated with snippets.

Schema

A snippet looks like this:

{
    "id": "638586a8b7",
    "title": "Hi world",
    "description": "This code screams Hi World.",
    "code": "console.log('hi world')",
    "views": 26,
    "language": {
        "id": 6,
        "name": "JavaScript"
    },
    "category": {
        "id": 3,
        "name": "Free lines"
    },
    "votes": 99999,
    "username": "trains",
    "createdAt": "2018-03-19T23:48:30.000Z",
    "updatedAt": "2018-03-19T23:48:30.000Z"
}

Snippets, unlike most other API objects, have string unique IDs rather than integer ones.

  • username is the username of the owner user
  • language and category are language and category objects (See their own reference)
  • title is a length-limited string
  • description is a limitless (to an extent), but optional, string. If the user includes markdown in their description, then, well, description will contain the markdown as well. You need to parse that.
  • code is also limitless.
  • views represents the number of views, obviously.
  • createdAt and updatedAt are dates of creation and update, respectively, in UTC, and in ISO 8601. If updatedAt is identical to createdAt, then the snippet was never edited.
  • votes is the sum of down and upvotes for the given snippet, and,

There are extra properties given by certain end-points, which will be covered below.

Getting latest snippets

We have implemented an end-point to get the latest 30 snippets (we sometimes change that number 🤔) to help create feeds and browse sections.

The end-point is GET /snippets, when given no parameters, (read right below to know why)

It never throws errors, and the response is an array of snippets.

Searching snippets

The end-point is GET /snippets (same as above), but takes these parameters:

Parameter Required? Description Example
keywords Maybe (Yes, otherwise gets latest snippets) Keywords to be matched against snippets. Must be >2 chars Truncate string
language No The ID of the language to search for 1

Response is an array of snippets.

The end-point will return up to 10 results in the form of an array of snippets. ([] if no matches)

Here's the list of errors this end-point might throw:

HTTP status Error message
422 Keywords too short
422 Invalid language

Getting a snippet by ID

You can get a specific snippet by its ID. This returns more data than what other end-points return.

The end-point is GET /snippets/{id}, and will return a snippet object. (If found, obviously)

There are few extra properties this will return:

  • revisions, an integer representing the number of revisions this snippet has. 1 means the snippet has never been edited.
  • If authentication, currentVote is provided, representing the authenticated user vote. (1, -1, or 0)

The end-point takes no parameters and throws no errors (other than 404)

There should be far more end-points documented here but given that authentication is yet to be documented, they are omitted for now.