-
Notifications
You must be signed in to change notification settings - Fork 0
API
One of the key aspects on Neon is that it should be open and extensible so we therefore wrote an API that gets used by both the JavaScript client side and is accessible to anyone else so that you can write apps that work on top of someone's Neon account. This documentation is preliminary and subject to change however contains basic detail on how you can use the API.
The API uses GET and POST requests and returns JSON. We use JSON purely over XML because all our server and client side code is written in JavaScript so it makes sense to use a technology that will work out the box with as little extra code as possible. Because posts are not publicly accessible we haven't implemented RSS/XML either.
All requests will go through http://server-route:port/api/ and will return JSON regardless of what happens (unless the server crashes). All responses will contain a JSON object in this style:
{
"request": {
"requestType": "requestType",
"requestDetail": "requestDetail",
"successCode": 200
}
}The requestType indicates what was requested, such as dashboard, user or inbox. Request detail will give the extra, optional part of the request, such as 20 for the request api/user/20. The success code is a standard HTTP request. Currently it will return things such as the following:
- 200: Success
- 400: More information required
- 401: Unauthorized
- 404: Not found
The HTTP status code returned in the header will always match the success code in case your application checks that. Please note that response section is not included in any other response examples in this documentation however will always be returned.
We wanted to be lazy when we wrote Neon so therefore there are only two methods of authentication. The first, which we use in the JavaScript client side code, is to send the username and password via a POST request to /api/login/. Here is an example:
Request:
POST: /api/login?username=exampleUsername&password=examplePassword
Response:
{
"login": {
"username":"exampleUsername",
"key":"abcdefghijklmnopqrstuvwxyz012345abcdefghijklmnopqrstuvwxyz012345"
}
}The key is randomly generated on the server and will work for up to a month, at which point the key will expire and you will receive a 401 response, requiring you to login again. Each time you make a request you should also send the username and key. This is beneficial for GET requests as it doesn't contain the password and is therefore less easy to watch, and it also means that you never have to store the password client side.
Alternatively you can authenticate requests by sending username and password for each request however we don't believe that this is as secure.
The following is an incomplete list of all of the API options. We intend to keep this documentation up to date. Please note that all requests require the username and key or password property. If you are learning the API you may wish to add the optional whitespace parameter to get easier to read JSON.
This request allows you to fetch user information and the most recent posts that are visible to the logged in user. This means that the user information is public, however only posts that were submitted to groups that you and the user are members of will be visible. You can use either a GET or POST request to access this.
By default, the fifty most recent posts are returned however if you want to request earlier posts please use offset=integer where integer begins at 0 for the most recent post.
Example requests:
GET /api/user/20
GET /api/user/thomas
GET /api/user/20?offset=20
POST /api/user/20?offset=50
Example response:
{
"user":{
"userId":20,
"username":"thomas",
"name":"Thomas :)",
"groupIds":[12, 13, 14, 18],
"groupNames":["Socials", "Phsyics 11A", "Maths 11.1", "English 11M1"],
"userImage":"/images/20.png",
"posts":[
{
"postId":1,
"plainText":"Hello, world!",
"html":"<p>Hello, <em>world</em>!",
"groupId":12,
"groupName":"Socials",
"groupColor":"#123456",
"likes":10,
"dislikes":1,
"reposts":[7,8,10,24],
"jsonTime":"Sat Oct 20 2012 16:33:08 GMT+0100 (GMT Daylight Time)",
"time":1234567890
},...
]
}
}The group IDs and Names are all the groups that a user is a member of. Each post is a simplified version of a standard post response and contains the key information. For information, scroll to the Dashboard section.
###/api/group/
This request allows you to get information about a specific group either through a GET or POST request. You will only get post data from the group if the user whose details you are using is a member of that group. Like /api/user/ and /api/dashboard/ requests this will quite happily accept an offset parameter.
Example requests:
GET /api/group/1
GET /api/group/1?offset=10
POST /api/group/1?offset=50
Example response if the user is not able to see posts:
{
"group":{
"groupId":1,
"groupName":"Staff",
"groupCreator":{
"userId":20,
"username":"thomas",
"name":"Thomas :)",
"groupIds":[1, 12, 13, 14, 18],
"groupNames":["Socials", "Phsyics 11A", "Maths 11.1", "English 11M1"],
"userImage":"/images/20.png"
},
"groupColor":"#123456"
}
}Example response if is able to read posts:
{
"group":{
"groupId":1,
"groupName":"Staff",
"groupCreator":{
"userId":20,
"username":"thomas",
"name":"Thomas :)",
"groupIds":[1, 12, 13, 14, 18],
"groupNames":["Socials", "Phsyics 11A", "Maths 11.1", "English 11M1"],
"userImage":"/images/20.png"
},
"groupColor":"#123456",
"posts":[
{
"postId":1,
"plainText":"Hello, world!",
"html":"<p>Hello, <em>world</em>!",
"userId":20,
"username":"thomas",
"name":"Thomas :)",
"likes":10,
"dislikes":1,
"reposts":[7,8,10,24],
"jsonTime":"Sat Oct 20 2012 16:33:08 GMT+0100 (GMT Daylight Time)",
"time":1234567890
},...
]
}
}The group ID is the database ID required for the request. The groupColor property isn't really needed by many applications but you may wish to show it when presenting which group a user posted a post in. We allow the group creator to change the group color however we may only get the Hue value from the hex code and set our own brightness and saturation levels. It is worth noting that members of a group are not returned because this will usually produce a very large array and it isn't needed by our client.
###/api/dashboard/
This can be used as a GET or POST request to get the posts for the current users' dashboard. This will include all posts from all groups that they are a member of. Again, this allows for an offset property to fetch older posts.
Example requests:
GET /api/dashboard
POST /api/dashboard
GET /api/dashboard?offset=50
Example response:
{
"posts":[
{
"postId":1,
"plainText":"Hello, world!",
"html":"<p>Hello, <em>world</em>!",
"userId":20,
"username":"thomas",
"name":"Thomas :)",
"likes":10,
"dislikes":1,
"reposts":[7,8,10,24],
"jsonTime":"Sat Oct 20 2012 16:33:08 GMT+0100 (GMT Daylight Time)",
"time":1234567890,
"groupId":12,
"groupName":"Socials",
"groupColor":"#123456",
},...
]
}Again, if the user is not authenticated no posts will be returned. We also recommend that there is a general group for all users so that therefore some posts will be returned.