SWAbooru is built off of Danbooru, which uses a REST-like API. Here is some basic API documentation.

To create your own API key. Go to swaggerswithattitude.com/users/[YourUIDhere]/api_keys.

Testing

There is no testing URL for https://swaggerswithattitude.com at the moment so everything you try will happen on the website.

Basics

HTTP defines four basic request methods: GET, POST, PUT and DELETE. You'll be using these methods to interact with the Danbooru API. Most API calls that change the state of the database (like creating, updating, or deleting something) require an HTTP POST, PUT or DELETE call. API calls that only retrieve data can typically be done with an HTTP GET call.

An example of a GET with no API key involved would be this:

curl -X GET "https://swaggerswithattitude.com/posts/23.json"

(If you want a more readable file then replace the .json with .xml)

A URL is considered a resource and the HTTP methods are actions you perform on the resource. For example, GET /posts/23.json returns a JSON representation of post #23. GET /posts/23.xml returns an XML representation. PUT or PATCH /posts/6.json would update the resource, for example changing its tags.

Some resources require parameters. For example, you can find tags that start with the letter 'a' by calling GET /tags.json?search[name_matches]=a*. This will give you a JSON listing of all tags with names starting with an a.

For POST, PUT and DELETE requests you must pass these parameters along in the body instead of the query parameters. Body parameters may be encoded in one of two ways. The usual way is with key-values pairs using "Content-Type: application/x-www-form-urlencoded":

curl -u "$login:$api_key" -X PUT "https://swaggerswithattitude.com/posts/6.json" -d 'post[rating]=s&post[tag_string]=swaggers'

Parameters may also be encoded as JSON using "Content-Type: application/json":

curl -u "$login:$api_key" -X PUT "https://swaggerswithattitude.com/posts/6.json" -d '{ "post": { "rating": "s", "tag_string": "swaggers" } }' -H "Content-Type: application/json"

Responses

All API calls that change state will return a single element response (for XML calls). They are formatted like this:

<?xml version="1.0" encoding="UTF-8"?>
<response success="false" reason="duplicate"/>

For JSON responses, they'll look like this:

{ "success": false, "reason": "duplicate" }

While you can usually determine success or failure based on the response object, you can also figure out what happened based on the HTTP status code. In addition to the standard ones, SWAbooru uses some custom status codes in the 4xx and 5xx range.

• 200 OK: Request was successful
• 204 No Content: Request was successful (returned by create actions)
• 400 Bad Request: The given parameters could not be parsed
• 401 Unauthorized: Authentication failed
• 403 Forbidden: Access denied (sensitive/important files or folders Chef doesn't want you to touch or were considered sensitive by default for Danbooru)
• 404 Not Found: Not found (could be a typo)
• 410 Gone: Pagination limit
• 420 Invalid Record: Record could not be saved
• 422 Locked: The resource is locked and cannot be modified
• 423 Already Exists: Resource already exists
• 424 Invalid Parameters: The given parameters were invalid
• 500 Internal Server Error: A database timeout, or some unknown error occurred on the server
• 502 Bad Gateway: Server cannot currently handle the request, try again later (returned during heavy load)
• 503 Service Unavailable: Server cannot currently handle the request, try again later (returned during downbooru What the fuck is downbooru?)

Authentication

You will need an API key if you need to login using the API. To authenticate with the API, pass the login and api_key URL parameters, where login is your username and api_key is your API key:

https://swaggerswithattitude.com/profile.json?login=your_username&api_key=your_api_key

You can also authenticate using HTTP Basic Authentication:

curl "https://$username:[email protected]/profile.json"
curl --user "$username:$api_key" https://swaggerswithattitude.com/profile.json

Most HTTP libraries support HTTP basic authentication out of the box. If yours doesn't, you can generate the authentication header manually. The format is Authentication: Basic $secret where $secret = base64($username + ":" + $api_key). In other words, concatenate your username and API key together, separated by a colon, then Base64 encode the result:

curl --header "Authorization: Basic $(printf "%s" "$username:$api_key" | base64)" https://swaggerswithattitude.com/profile.json

If you are writing a user script for a browser, you do not need to embed an API key. You can rely on the user's session.

VERY FUCKING IMPORTANT TO READ THIS! Keep your API key secret as if the feds are onto you. Treat it like as if it's your password because it might as well be a second password. Getting a hold of someones API key allows full access to their account. Never publicly post your API key or distribute it in your scripts.

View wiki