Gist Fox API

Gist Fox API is a pastes service similar to GitHub’s Gist.

Authentication

Currently the Gist Fox API does not provide authenticated access.

Media Types

Where applicable this API uses the HAL+JSON media-type to represent resources states and affordances.

Requests with a message-body are using plain JSON to set or update resource states.

Error States

The common HTTP Response Status Codes are used.

Resource Group

Gist Fox API Root

Gist Fox API entry point.

This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and HAL links.

Retrieve the Entry Point

GET

/

Response 200Toggle

Headers

Content-Type: application/hal+json
Link: <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists"

Body

{
    "_links": {
        "self": { "href": "/" },
        "gists": { "href": "/gists?{since}", "templated": true }
    }
}

Gist

Gist-related resources of Gist Fox API.

Gist

A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note.

The Gist resource has the following attributes:

id
created_at
description
content

The states id and created_at are assigned by the Gist Fox API at the moment of creation.

Retrieve a Single Gist

GET

/gists/{id}

Parameters
id
string (required)
ID of the Gist in the form of a hash.

Response 200Toggle

HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.

Headers

Content-Type: application/hal+json
Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"

Body

{
    "_links": {
        "self": { "href": "/gists/42" },
        "star": { "href": "/gists/42/star" },
    },
    "id": "42",
    "created_at": "2014-04-14T02:15:15Z",
    "description": "Description of Gist",
    "content": "String contents"
}

Edit a Gist

PATCH

/gists/{id}

To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash.

Parameters
id
string (required)
ID of the Gist in the form of a hash.

RequestToggle

Headers

Content-Type: application/json

Body

{
    "content": "Updated file contents"
}

Response 200Toggle

HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.

Headers

Content-Type: application/hal+json
Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"

Body

{
    "_links": {
        "self": { "href": "/gists/42" },
        "star": { "href": "/gists/42/star" },
    },
    "id": "42",
    "created_at": "2014-04-14T02:15:15Z",
    "description": "Description of Gist",
    "content": "String contents"
}

Delete a Gist

DELETE

/gists/{id}

Parameters
id
string (required)
ID of the Gist in the form of a hash.

Response 204

Gists Collection

Collection of all Gists.

The Gist Collection resource has the following attribute:

total

In addition it embeds Gist Resources in the Gist Fox API.

List All Gists

GET

/gists{?since}

Parameters
since
string (optional)
Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ Only gists updated at or after this time are returned.

Response 200Toggle

HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation.

Headers

Content-Type: application/hal+json
Link: <http:/api.gistfox.com/gists>;rel="self"

Body

{
    "_links": {
        "self": { "href": "/gists" }
    },
    "_embedded": {
        "gists": [
            {
                "_links" : {
                    "self": { "href": "/gists/42" }
                },
                "id": "42",
                "created_at": "2014-04-14T02:15:15Z",
                "description": "Description of Gist"
            }
        ]
    },
    "total": 1
}

Create a Gist

POST

/gists{?since}

To create a new Gist simply provide a JSON hash of the description and content attributes for the new Gist.

RequestToggle

Headers

Content-Type: application/json

Body

{
    "description": "Description of Gist",
    "content": "String content"
}

Response 201Toggle

HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links.

Headers

Content-Type: application/hal+json
Link: <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"

Body

{
    "_links": {
        "self": { "href": "/gists/42" },
        "star": { "href": "/gists/42/star" },
    },
    "id": "42",
    "created_at": "2014-04-14T02:15:15Z",
    "description": "Description of Gist",
    "content": "String contents"
}

Star

Star resource represents a Gist starred status.

The Star resource has the following attribute:

starred

Star a Gist

PUT

/gists/{id}/star

Parameters
id
string (required)
ID of the gist in the form of a hash

Response 204

Unstar a Gist

DELETE

/gists/{id}/star

Parameters
id
string (required)
ID of the gist in the form of a hash

Response 204

Check if a Gist is Starred

GET

/gists/{id}/star

Parameters
id
string (required)
ID of the gist in the form of a hash

Response 200Toggle

HAL+JSON representation of Star Resource.

Headers

Content-Type: application/hal+json
Link: <http:/api.gistfox.com/gists/42/star>;rel="self"

Body

{
    "_links": {
        "self": { "href": "/gists/42/star" },
    },
    "starred": true
}