API v1 Reference

API v1 Reference

Description

The ourJSON APIv1 emulates the myJSON for the most part, and it is built around the concept of bins. If you've worked with MongoDB (or another document-based NoSQL DB before, bins are the conceptual equivalent of documents.)

Endpoints

/bins

####POST /bins

POST-ing to this endpoint creates a bin. Creating 'vanity' bin-ids (i.e. specifying the id to be created) is not currently supported although there are potential thoughts to support this in the future.

Example Request: POST /bins/

{
  "foo": "bar",
  "baz": 5,
  "quot": null
}

Success (Response Code: 201 Created)

{
  "uri": "<protocol>://<base-url>/bins/<assigned BinID>"
}

Failure (Response Code: 5xx Internal Server Error)

{
  "status": "<5xx>",
  "message": "Internal Server Error",
  "description": "<Error message>"
}

/bins/:binId

####GET /bins/:binId

GET-ting from this endpoint with a valid binId will return the data referenced by that binId. If no bin with that binId is found, a 404 Not Found error is returned. If not binId is provided, a null binId is passed, and thus a 404 Not Found error is also returned.

Example request: GET /bins/foobar12

Success (Response Code: 200 OK)

{
  "data": "from the bin",
  "appears": "in the body of the response"
}

Failure (Response Code: 5xx Internal Server Error, 404 Not Found)

{
  "status": "<5xx/4xx>",
  "message": "Internal Server Error/Not Found",
  "description": "<Error message>"
}

####PUT /bins/:binId

PUT-ing to this endpoint with a valid binID replaces the entire document with the one in the body of the PUT request. This may seem counter-intuitive at first, but it was a conscious decision not to perform a deep merge of only the changed fields PUT-ted in order to maintain full compatibility with the myJSON API. The APIv2 development roadmap includes a deep merge mode.

Exmaple request: PUT /bins/foobar12

{
  "updated": "full data from the bin",
  "appears": "in the body of the response"
}

Success (Response Code: 200 OK)

{
  "updated": "full data from the bin",
  "appears": "in the body of the response"
}

Failure (Response Code: 5xx Internal Server Error, 404 Not Found)

{
  "status": "<5xx/4xx>",
  "message": "Internal Server Error/Not Found",
  "description": "<Error message>"
}

####DELETE /bins/:binId

DELETE to this endpoint with a valid binID will delete the bin from storage. It is important to note that there is no recycle-bin functionality in place. Also, by default, there are no access-control mechanisms on the DELETE function, although it should be a trivial matter to extend the restify server with an auth middleware.

Exmaple request: DELETE /bins/foobar12 Success (Response Code: 200 OK)

{
  "status": 200,
  "message": "Success",
  "description": "Bin <binId> has been deleted."
}

Failure (Response Code: 5xx Internal Server Error, 404 Not Found)

{
  "status": "<5xx/4xx>",
  "message": "Internal Server Error/Not Found",
  "description": "<Error message>"
}

/bins/export

POST /bins/export?format=<json|mongoexport>

POST-ing to this endpoint with a JSON array of binIds in the body of the post will return:

Format type: json (if no format type is defined, json is the default)

Returns: A JSON object with a data attribute and optionally, an err attribute.

This format will output objects in regular JSON in a JSON Array on the data attribute, similar to the output of the GET request on /bins/binId, except it outputs all the binIds requested. If some binIds fail to parse, the response object will contain an err attribute, which is an array of all binIds that were not found/caused errors.

Format type: mongoexport

Returns: A JSON Array in MongoDB strict mode of all the binIds successfully retrieved.

This format uses mongoexport internally and pipes the output data directly into the response. As such, it uses mongodb's strict mode to preserve type information. While a regular JSON parser will be able to parse this output format, it will result in weird field names (i.e. { "$binary": "<bindata>", "$date": "ISODate()" }) that are only meant for the JSON parser in mongoimport or the mongo shell to understand. However, because this achieves better data parity than regular JSON, and has a chance of maintaining parity in Mongo ObjectIDs, this is the preferred format when exporting data that is meant to be imported into another Mongo database.

Example request: POST /export?format=json

["foobar12", "bazquot34", "loremips56"]

Success (Response Code: 200 OK)

{
  "data": [
    {
      "binId": "foobar12"
    },
    {
      "binId": "bazquot34"
    },
    {
      "bindId": "loremips56"
    }
  ]
}

or with partial errors:

{
  "data": [
    {
      "binId": "foobar12"
    },
    {
      "bindId": "loremips56"
    }
  ],
  "err": ["bazquot34"]
}

Failure (Response Code: 5xx Internal Server Error, 404 Not Found)

{
  "status": "<5xx/4xx>",
  "message": "Internal Server Error/Not Found",
  "description": "<Error message>"
}