Shivtr

Getting Started

Shivtr provides a JSON REST API you can use to interact with the site and its data. The API can be used for such tasks as creating widgets that show data from Shivtr, mobile or web apps that connect with Shivtr, or even in-game apps that integrate with Shivtr.

REST API
Shivtr's API is built around the RESTFUL design model. This means the HTTP Verb you send with your request is stating the action you wish to perform.

VERB RESULT
GET Fetch an object or list of objects
POST Create a new object
PATCH Update an object
DELETE Delete an object


Here are a few examples of API requests you can make

Fetch list of characters
GET http://enmity.shivtr.com/characters.json

Create a new character
POST http://enmity.shivtr.com/characters.json

Fetch character 275561
GET http://enmity.shivtr.com/characters/275561.json

Update character 275561
PATCH http://enmity.shivtr.com/characters/275561.json

Delete character 275561
DELETE http://enmity.shivtr.com/characters/275561.json


JSON API
Shivtr's API uses JSON, JavaScript Object Notation, to serialize data into a simple format to work with.

Sample JSON Object
{
"user": {
"email": "snafzg@email.com",
"password": "xyz789"
}
}


Working with JSON makes it fast and easy to build javascript applications that make use the API.

We recommend using an addon such as JSONView, which will provide pretty output for your json

Permissions
The API makes the same requests you make using the website, except it serializes the data to JSON. Because requests are made through the same interface, permissions work exactly the same with the API as they do the website.

When using the API as a guest, you have the same permission for viewing content a guest would when visiting your website; similarly you may only perform the same actions using the API that a guest may perform on your website.

When using the API as an authenticated user, you have the same permissions as you would on the website. This means you can view, create, edit or delete the same content with the API as you could using the website; any action you do not have permission to perform on the website will return the same "Not Authorized" message with the API.

Testing With Curl
Curl is a great command line tool for making requests to a web server, and can help with testing the API. If you don't have Curl installed on your computer, it can be downloaded from their official site.

Curl accepts several options that can be set with the request, here's a few you should know:

Option Explain
-H Specifies extra headers to send with the request
-d Specifies data to send with the request
-X Specifies the http verb to send: GET, POST, PUT or DELETE
-v Makes curl more verbose, showing headers and useful info for debugging


Sample Curl GET Request
curl -H "Content-Type: application/json" -v \
http://your-site.shivtr.com/characters.json \


Sample Curl PUT Request
curl -H "Content-Type: application/json" -v \
http://your-site.shivtr.com/characters/1000.json?auth_token=abcdef123456 \
-X PUT \
-d '{"character":{"name":"Snafzg","level":"50"}}'