NeoAPI

Follow @neoapi     API calls     neoapi forum     Get Developer Token     Register App

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.

[edit] Status

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.

[edit] NeoAPI 2011

[edit] OAuth Support

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.

[edit] 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

[edit] 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:

/status_updates/$activityid/

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

[edit] Using the API

Developers interested in using the API need only call the URLs to receive JSON responses.

The API can be used with any programming language that can read a file across the http protocol and parse the JSON response, such as Javascript, PHP (via json_decode), the .NET framework languages (using an external library), C++ (using an external library), and many more languages.

[edit] Using the API in your app

You need to register an app with Neoseeker and make authenticated calls using OAuth.

Examples:

  • PHP:
    • Make authenticated calls using PHP's OAuth class.
    • use json_decode to convert our json response into native PHP variables that you can use directly in your code.

[edit] 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:

http://api.neoseeker.com/ntags/translate.json?dev_token=__token__&string=hello%20%27%27%27bold%27%27%27&for=pm

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.

[edit] NeoAPI Standards

  • 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.

[edit] 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.

Eg:

http://api.neoseeker.com/forum/get_pm_counts.json?callback=foo

Note that when we output JSONP, the NeoAPI will send a header of type "javascript" instead of "json" so that clients can rely on content type without testing whether the API response has padding or not:

Content-type: application/javascript

[edit] 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.

[edit] User

[edit] Forum

[edit] Current API calls

A fully documented list of API calls which includes detailed examples is now on our NeoAPI call documentation site:

http://api.neoseeker.com/docs/

[edit] Current Private and Legacy Calls

The below are calls that are currently for private internal use only.

[edit] Forum

[edit] nTags

[edit] Site

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.

[edit] Getting Help

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.

Last edited by Redemption on 2 June 2011 at 17:45
This page has been accessed 4,285 times.