The Neoseeker API is a web services interface to Neoseeker data that 3rd party developers can use to build web and desktop applications that interface with Neoseeker's community and content.
The Neoseeker API is in its infancy, and currently supports a growing number of read and write requests. We will be expanding these API calls to service our own needs and those of developers. Currently, Neoseeker is working with Artificer so that the API can be used to provide stable information for NAMFox, as well as Chiggins for a desktop/Android application. The NeoAPI will also power Neoseeker's own initial iPhone App.
Follow us on Twitter @neoapi for updates on the API.
The NeoAPI supports OAuth for authenticating users. With OAuth support, the NeoAPI enables developers to create apps that hook straight into a user's account without the app having to insecurely store the user's password and transmit it to the API. OAuth is the standard used by Facebook and Twitter in their APIs, which means that it will be familiar for those coming from, or moving to development of apps for those platforms.
RESTful API Interface with Connections
The NeoAPI's current and new calls use a RESTful API model that supports Connections (based on Facebook's excellent Graph API). This means that developers will have access to a broad range of "objects" on Neoseeker, each of which have "connections" as callable API responses. A "connection" is simply a list of other objects that are connected to the object you are calling.
For example, forum threads and messages are individual "objects", and you can get the messages connection of a forum thread from the thread object:
/forumthreads/$threadid/ <-- object that contains info about a thread, such as # of replies, last reply date, etc. /forumthreads/$threadid/messages <--- connection that shows the messages within a thread /threadmessages/$messageid/ <-- object that contains details about a single message
This framework for the API is very intuitive because there will be a few number of core objects with very intuitive connections. Some example objects include
- members - threads - thread messages - pm threads - private messages - news - galleries - gallery images
If you consider the connection model you will find common ones for comments, likes, favourites, etc.
Some example potential connections for the members object
/members/$memberid/friends /members/$memberid/blogposts /members/$memberid/comments /members/$memberid/status_updates /members/$memberid/favourites /members/$memberid/likes /members/$memberid/forum_messages
How Connections Relate to Objects
If you consider the example of the member object, which has a connection called "status_updates", that connection lists all the status updates that the user has made. Each status update itself is an object, which can be found in the status update object such as:
And connections for this status update would include:
/status_updates/$activityid/likes <-- a list of members who liked this /status_updates/$activityid/favourites <-- a list of members who favourited this /status_updates/$activityid/comments <-- comments on the status update
Now if you take the comment, each comment is an object, so a hypothetical comment might have the following object and connections:
/comments/$activityid/likes <-- members who liked this commment
Using the API
Developers interested in using the API need only call the URLs to receive JSON responses.
Using the API in your app
Demo API calls
As of spring 2011, we no longer support public API (aka non-authenticated) calls. To demo our API calls as a developer, you need a Developer Token. To get one, request a developer token and append the token in the query string (as dev_token) of the API request like the following:
Beware of any use of this token, DO NOT forward this token to anyone. This developer token will authenticate the user as you.
If you are suspecting invalid use of your developer token, you may choose it to reset it any time.
- all calls use underscores instead of camelCaps
- all calls return JSON code
- For simple responses of a single piece of data, calls are returned as raw strings, int, or boolean
- true/false responses always return as boolean type (viewing the response will appear to show a string of the word true or false, but because it isn't wrapped in quotes it is treated by your native language as true/false boolean).
- For calls that return multiple pieces of data, data is returned as arrays of objects with keynames where appropriate. This allows client side languages to take advantage of array keys, while languages like JS can ignore them and iterate through the array of data.
JSONP for use on Cross Domain Code
By default NeoAPI returns JSON with a content-type headers of application/json.
Starting November 28th, 2010, Neoseeker API calls accept a callback to return JSONP.
Deprecated API calls
The following API calls will soon to be deprecated and replaced by new URL structure. We will continue to support them as read-only calls as long as NAMFox requires them.
Current API calls
A fully documented list of API calls which includes detailed examples is now on our NeoAPI call documentation site:
Current Private and Legacy Calls
The below are calls that are currently for private internal use only.
- forums (private)
- translate (private)
- search (private)
API calls marked as private require OAuth or a developer key for use. We will be opening many of these to users once we complete our API keys distribution system.
If you need help with the API, join us in the NeoAPI forum to discuss how to use the API, demonstrate what you've made, or share suggestions and ideas.