IsCrapBecause.It

Ooh, an API (in beta)

We're making an API that lets you write a program that can get data from us.
You are very welcome to use this API on a few conditions:

  1. Get permissions from us first. Send us an email or something. Not only does it let us know who is using the data and what for, it also means we can let you know if you're doing something that's already been done.
  2. Don't batter our servers. Work out cunning ways to use caches and such please. It'll stop our server crying.
  3. Link back to us. In the text you display, please link at least the Thing name back to it's correct page. When you get data, there is a field called "link" with a handy URL in.
  4. Let us know if you find a bug. There will be plenty, and with your help we can fix them.
  5. Understand that whilst we will do all we can to stop the offensive stuff, we're not cyborgs (yet). If you use the API, do so at your own risk.
  6. If you start making money from our data, please get in touch first to work out some agreement.

Using the API.

To use the API you need to point whatever program you are writing to: http://iscrapbecause.it/api.php

By default the server should return a random Thing and Reason in XML. TO change what you get back you can add the following variables to the URL;

format

XML returns the data in XML form.
HTML returns a basic HTML formatted list with the data in.
JS (the default) returns a line of JavaScript which document.write to diplay the standard HTML results.
JSON returns the data in JavaScript Object Notation form.
JSONP (otherwise known as JSON with padding) returns the data in JSNOP form. If you want to use this you have to also give jsonp_callback which is the name of the callback function.

resource

random (default) returns a random Thing and Description
thing returns a specific Thing and all of the Reasons associated with it. You need to provide either thing_name which is the name of the Thing, or thing_id which is its ID.
reason returns a specific Reason. You need to provide reason_id which is the ID of the reason.
list returns a list of the most recently added Things and Reasons

number

How many results do you want? There is a maximum (currently 10) and some function calls only return one thing regardless.

allow

Set to all if you want to be able to access all the data in the system. Otherwise you'll only be given results that have been staff approved (much safer).

score

Give the minimum score (Good votes minus Crap votes) a reason must have. Defaults to 0. This is only used when either a random, or multiple reasons are returned.

Errors

200 Everything is fine
101 The resource could not be found
102 The Thing could not be found
103 The Reason could not be found
104 An unknown or uncommon error occured
105 No callback was found for a JSONP request
106 The requested format could not be found
107 No ID value was given in a request for a Reason

Examples

In XML, the most recent five Things and Reasons:
http://iscrapbecause.it/api.php?format=XML&resource=list&number=5

In JSON form, three reasons why Wardrox is crap:
http://iscrapbecause.it/api.php?format=JSON&resource=thing&thing_name=wardrox&number=3

In JSONP form with a callback called ICBICallback, two random Things and Reasons:
http://iscrapbecause.it/api.php?format=JSONP&jsonp_callback=ICBICallback&resource=random&number=2

In HTML form, five random Things and Reasons that have a score above 5, unfiltered:
http://iscrapbecause.it/api.php?format=HTML&resource=random&number=5&score=&allow=all