Gist Fox API


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

Authentication

Gist Fox API uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token’ scope.

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.

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

REQUEST

GET

/

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/>;rel="self",<http:/api.gistfox.com/gists>;rel="gists",<http:/api.gistfox.com/authorization>;rel="authorization"
200 application/hal+json
                        {
    "_links": {
        "self": { "href": "/" },
        "gists": { "href": "/gists?{since}", "templated": true },
        "authorization": { "href": "/authorization"}
    }
}

                      
                        
                      
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

REQUEST

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"
200 application/hal+json
                        {
    "_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

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.

REQUEST

Headers
Content-Type application/json
application/json
                          {
    "content": "Updated file contents"
}

                        
                          
                        

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"
200 application/hal+json
                        {
    "_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

REQUEST

RESPONSE

Headers
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

REQUEST

Parameters
since string

Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ Only gists updated at or after this time are returned.

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/gists>;rel="self"
200 application/hal+json
                        {
    "_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

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

This action requires an access_token with gist_write scope.

REQUEST

Parameters
access_token string

Gist Fox API access token.

Headers
Content-Type application/json
application/json
                          {
    "description": "Description of Gist",
    "content": "String content"
}

                        
                          
                        

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/gists/42>;rel="self", <http:/api.gistfox.com/gists/42/star>;rel="star"
201 application/hal+json
                        {
    "_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

This action requires an access_token with gist_write scope.

REQUEST

RESPONSE

Headers

Unstar a Gist

This action requires an access_token with gist_write scope.

REQUEST

RESPONSE

Headers

Check if a Gist is Starred

REQUEST

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/gists/42/star>;rel="self"
200 application/hal+json
                        {
    "_links": {
        "self": { "href": "/gists/42/star" },
    },
    "starred": true
}

                      
                        
                      
Access Authorization and Control

Access and Control of Gist Fox API OAuth token.

Authorization

Authorization Resource represents an authorization granted to the user. You can only access your own authorization, and only through Basic Authentication.

The Authorization Resource has the following attribute:

  • token

  • scopes

Where token represents an OAuth token and scopes is an array of scopes granted for the given authorization. At this moment the only available scope is gist_write.

Retrieve Authorization

REQUEST

Headers
Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

RESPONSE

Headers
Content-Type application/hal+json
Link <http:/api.gistfox.com/authorizations/1>;rel="self"
200 application/hal+json
                        {
    "_links": {
        "self": { "href": "/authorizations" },
    },
    "scopes": [
        "gist_write"
    ],
    "token": "abc123"
}

                      
                        
                      

Create Authorization

REQUEST

Headers
Content-Type application/json
Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
application/json
                          {
    "scopes": [
        "gist_write"
    ]
}

                        
                          
                        

RESPONSE

Headers
                        [Authorization][]

                      
                        
                      

Remove an Authorization

REQUEST

Headers
Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

RESPONSE

Headers