IntroductionThe Snipt.org API uses a REST service model. Currently the POST route is used for updating, creating, and removing data while GET is used to retrieve data. The API currently uses JSON-encoded results to maintain an object-oriented structure. The base URL for accessing the API is http://api.snipt.org. AuthorizationThe Snipt.org API uses Twitter to perform authorization using a twitter username/password. You must have a twitter account to use the Snipt.org API. In order to better protect service calls, you must first obtain a token from the API to communicate with it. This token is good for up to 8 hrs after your last call, after which point you will receive an error and need to re-authorize. CRUD actions can only be performed on Snipt(s) which you have permission to edit, aka: those in your snipt box. If you need to edit other snipts, you will need to obtain a new token using the twitter user/pass of the owner of that snipt. Wrapping ResultsAll service calls take an optional "&useWrapper" param which, when set to true, will return the results using a resultWrapper object (see below). The default is false; Basic ObjectsHere are the basic objects returned by the Snipt API, and their properties. Result Wrapper Object- object returned when "userWrapper" is enabled
- properties
- functionName - name of the service endPoint result is from
- result - result of the service call
Error Object- object returned when something goes wrong
- properties
- error - true
- code - error code (see below)
- message - the message of the error
Snipt Object- object returned when creating/editing/getting/deleting a snipt
- properties
- ID - the id of the snipt (which you access via snipt.org/sniptID)
- title - snipt title
- content - the content
- htmlContent - the highlighted content in HTML format
- language - the language
- isPrivate - if this snipt is private (true/false)
- showNums - if line numbers should be shown for this snipt (true/false)
- theme - Theme Object (see below)
- twitterUser - (optional) twitter user this snipt belongs to.
Theme Object- object describing a theme, all colors are HEX with no '#' before them
- properties
- themeID - the id of the theme
- themeName - theme name
- fontSize - overall font size
- font - overall font
- overallColor - overall color
- varColor - var color
- keywordColor - keyword color
- methodColor - method name color
- commentColor - comment color
- stringColor - string color
- numberColor - number color
- symbolColor - symbol color
- escColor - esc char(s) color
- bgColor - background color
Service Endpoints (functions)Here is a listing of all the currently available service functions, this will be updated as new ones are added. All endpoints operate off of the base 'http://snipt.org/api/ENDPOINT/?VARS'. Where ENDPOINT is the name of the function and VARS is a query string containing the parameters for that function (GET only). auth/- method: GET
- purpose: Authorizes a user using twitter API, returns a snipt API token or error object
- params
- username - twitter username
- password - twitter password
- return
- token - a token string representing this API session, you will need to pass this with all future calls
- twitterUser - A twitter user object returned from the twitter api - see docs here
getSnipt/- method: GET
- purpose: Retrieves a snipt object based on the supplied ID or error
- params
- ID - ID of the snipt being requested (ie:gHk)
- return
- Snipt Object - Snipt Object representing the requested snipt
getLanguages/- method: GET
- purpose: Retrieves array of languages currently supported by Snipt.org or error
- params
- return
- Array - Array of strings of all currently languages currently supported by Snipt.org
getThemes/- method: GET
- purpose: Retrieves all the current preset themes from Snipt.org or error
- params
- return
- Array - Array of Theme Objects representing all the preset themes on Snipt.org
getSniptBox/- method: GET
- purpose: Retrieves a snipt box based on the supplied username or error
- params
- username - Username of the box which you are trying to retrieve
- return
- Array - Array of Snipt Objects representing all snipts in this user's SniptBox
makeSnipt/- method: POST
- purpose: Creates a new snipt or returns error
- params
- content - Snipt content
- language - Language of the snipt
- title (optional) - Snipt title
- themeID (optional) - ID of the theme to be applied to this Snipt
- isPrivate (optional) - If this Snipt is private or not
- showNums (optional) - Whether or not to show line numbers for this Snipt
- twitterUser (optional) - Username of SniptBox of which to add this Snipt
- return
- Snipt Object - Snipt Object representing the newly created Snipt
editSnipt/- method: POST
- purpose: Updates a snipt or returns error
- params
- ID - ID of the Snipt to update (ie:gHk)
- content - Snipt content
- language - Language of the snipt
- title (optional) - Snipt title
- themeID (optional) - ID of the theme to be applied to this Snipt
- isPrivate (optional) - If this Snipt is private or not
- showNums (optional) - Whether or not to show line numbers for this Snipt
- twitterUser (optional) - Username of SniptBox of which to add this Snipt
- return
- Snipt Object - Snipt Object representing the updated Snipt
deleteSnipt/- method: POST
- purpose: Deletes a snipt or returns error
- params
- ID - ID of the snipt being deleted (ie:gHk)
- return
- Snipt Object - Snipt Object representing the deleted snipt
Error CodesHere are the different error codes and corresponding messages returned by the Snipt API. 100Theme does not exist. 101Snipt privacy setting mismatch. 102Snipt show line number setting mismatch. 103Snipt language not found. 104Elements missing. 105Error creating snipt via API. 106Error editing snipt via API. 107Snipt box empty. 108Theme does not exist. 109Error deleting snipt via API. 401API Authorization failed (is twitter down?). 404API endpoint not found. 300API token not found. 301APU token EXPIRED.
|
