Aviator logo Aviator

Getting Started

Welcome to our API.

This API document is designed for those interested in developing for our platform.

This API is still under development and will evolve.

You’ll succeed if you do this.

Here’s some useful information.

Something may not happen if you try and do this.

Something bad will happen if you do this.

Authentication

You need to be authenticated for all API requests. You can generate an API key in your developer dashboard.

Add the API key to all requests as a GET parameter.

Nothing will work unless you include this API key

$.get("http://api.myapp.com/books/", { "token": "YOUR_APP_KEY"}, function(data) {
  alert(data);
});

curl http://api.myapp.com/books?token=YOUR_APP_KEY

Errors

Code Name Description
200 OK Success
201 Created Creation Successful
400 Bad Request We could not process that action
403 Forbidden We couldn’t authenticate you

All errors will return JSON in the following format:

{
  "error": true,
  "message": "error message here"
}

/books

List all books

Parameters
offset
Offset the results by this amount
limit
Limit the number of books returned

This call will return a maximum of 100 books

Lists all the photos you have access to. You can paginate by using the parameters listed above.

$.get("http://api.myapp.com/books/", { "token": "YOUR_APP_KEY"}, function(data) {
  alert(data);
});

r = requests.get("http://api.myapp.com/books/", token="YOUR_APP_KEY")
print r.text

var request = require("request");
request("http://api.myapp.com/books?token=YOUR_APP_KEY", function (error, response, body) {
  if (!error && response.statusCode == 200) {
    console.log(body);
  }
});

curl http://sampleapi.readme.com/orders?key=YOUR_APP_KEY

[
  {
    "id": 1,
    "title": "The Hunger Games",
    "score": 4.5,
    "dateAdded": "12/12/2013"
  },
  {
    "id": 1,
    "title": "The Hunger Games",
    "score": 4.7,
    "dateAdded": "15/12/2013"
  },
]

{
  "error": true,
  "message": "Invalid offset"
}

/books

Create Book

Parameters
title
The title for the book
score
The book’s score between 0 and 5

The book will automatically be added to your reading list

Adds a book to your collection.

$.post("http://api.myapp.com/books/", {
  "token": "YOUR_APP_KEY",
  "title": "The Book Thief",
  "score": 4.3
}, function(data) {
  alert(data);
});

{
  "id": 3,
  "title": "The Book Thief",
  "score": 4.3,
  "dateAdded": "5/1/2015"
}

{
  "error": true,
  "message": "Invalid score"
}

/books/:id

Get Book

Returns a specific book from your collection

$.get("http://api.myapp.com/books/3", {
  token: "YOUR_APP_KEY",
}, function(data) {
  alert(data);
});

{
  "id": 3,
  "title": "The Book Thief",
  "score": 4.3,
  "dateAdded": "5/1/2015"
}

{
  "error": true,
  "message": "Book doesn't exist"
}

/books/:id

Update Book

Parameters
title
The title for the book
score
The book’s score between 0 and 5

Update an existing book in your collection.

$.ajax({
  "url": "http://api.myapp.com/books/3",
  "type": "PUT",
  "data": {
    "token": "YOUR_APP_KEY",
    "score": 5.0,
    "title": "The Book Stealer"
  },
  "success": function(data) {
    alert(data);
  }
});

{
  "id": 3,
  "title": "The Book Stealer",
  "score": 5,
  "dateAdded": "5/1/2015"
}

{
  "error": true,
  "message": "Book doesn't exist"
}

/books/:id

Deletes a book

Deletes a book in your collection.

$.ajax({
  "url": "http://api.myapp.com/books/3",
  "type": "DELETE",
  "data": {
    "token": "YOUR_APP_KEY"
  },
  "success": function(data) {
    alert(data);
  }
});

{
  "id": 3,
  "status": "deleted"
}

{
  "error": true,
  "message": "Book doesn't exist"
}