-
Notifications
You must be signed in to change notification settings - Fork 16
Mongo Server API
{
title: String,
url: String, // the url is the title scraped of invalid url characters (this is a relative reference on our site)
description: String,
stars: Number,
user: {
provider: String, // for third-party authentication
id: String, // id of user on third-party authentication system
fullName: String,
givenName: String
},
links: [
{
url: String, // external url of the link
title: String,
description: String
},{
// More links here...
}
]
}
Postman link to example queries: https://www.getpostman.com/collections/b82a082182ff730112f7
'POST to /api/collection/create'; Example POST data: {
"title": "A New Collection",
"description": "So many good links",
"user": {
"provider": "github",
"id": "1234",
"fullName": "John Johnson",
"givenName": "John"
},
"links": [
{
"url": "http://www.duck.com",
"title": "Ducks!",
"description": "So one might think"
}
]
};
Note: the value of the user property is currently populated by the userManagement Factory:
$scope.collection.user = userManagement.user;
On success, returns a collection data object:
{
// This is the model version generated by mongoose (can ignore for our purposes)
"__v":0,
// This is the unique collection id generated by MongoDB. Very useful for doing fast lookups
"_id":"540791bd17e7918007c35f5c",
"title":"A New Collection",
"url":"anewcollection", // Unique url, relative to our domain. With Angular: 'ourDomain.io/#/:url'
"description":"So many good links",
"stars":0, // Defaults to 0
"updatedAt":"2014-09-03T22:10:05.680Z",
"createdAt":"2014-09-03T22:10:05.679Z",
"user": {
"givenName":"John",
"fullName":"John Johnson",
"id":"1234",
"provider":"github"
},
"links": [
{
"url":"http://www.duck.com",
"title":"Ducks!",
"description":"So one might think",
"_id":"540791bd17e7918007c35f5d" // MongoDB generated unique id of this link
}
]
};
Returns null if an error occurs.
If there is an error, it might be because there is another collection with the same url. The server enforces unique urls.
This endpoint is flexible regarding inputs. You may only include properties where their values have changed. Alternatively, you can send the entire collection object and let the server decide what is different.
Example, where we send the entire collection object in JSON:
{
"_id":"540791bd17e7918007c35f5c",
"title": "A New Collection",
"description": "I've changed the description.", // THIS HAS CHANGED
"user": {
"provider": "github",
"id": "1234",
"fullName": "John Johnson",
"givenName": "John"
},
"links": [
{
"url": "http://www.duck.com",
"title": "Ducks!",
"description": "Nope, no ducks" // THIS HAS CHANGED
}
]
};
Returns a collection data object with the updated fields, everything else remains the same
{
"__v":0,
"_id":"540791bd17e7918007c35f5c",
<b>"description":"I've changed the description."</b>, // THIS HAS BEEN UPDATED
"title":"A New Collection",
"url":"anewcollection",
"user":{
"givenName":"John",
"fullName":"John Johnson",
"id":"1234",
"provider":"github"
},
"stars":0,
"updatedAt":"2014-09-03T22:30:21.363Z",
<b>"createdAt":"2014-09-03T22:10:05.679Z"</b>, // THIS HAS BEEN UPDATED
"links":[
{
"url":"http://www.duck.com",
"title":"Ducks!",
<b>"description":"Nope, no ducks"</b>, // THIS HAS BEEN UPDATED
"_id":"5407967d017c7988022579ba"
}
]
};
If the update errors, returns null
It is also possible to just send the data you would like to update. Here we are just adding a link. Note: This could also be via the addlink endpoint.
{
"_id":"540791bd17e7918007c35f5c",
"links": [
{
"url": "http://www.duck.com",
"title": "Ducks!",
"description": "Nope, no ducks"
},
{
"url": "http://www.duckduckgo.com",
"title": "Real Ducks",
"description": "Yay"
}
]
}
Another example, updating stars:
{
"_id":"540791bd17e7918007c35f5c",
"stars": 1
};
You can also update by title rather than _id. This is much slower than by _id, and not advised.
{
"title":"A New Collection",
"stars": 100
}
On error, returns null.
Note: Currently there is no validation on updates. This is on the todo. We must enforce no updates to immutable fields!
- _id
- title
- url
- user
- __v
Data required: JSON object of the collection id and data of the link(s) to be added in an array: Example:
{
"_id":"540791bd17e7918007c35f5c",
"link":[{
"url":"http://www.newurl.com",
"title":"New Url!",
"description":"Yep, definitely a new URL!"
}
]
}
On success, returns collection object:
{
"__v":0,
"_id":"540791bd17e7918007c35f5c",
"description":"I've changed the description.",
"title":"A New Collection",
"url":"anewcollection",
"user":{
"givenName":"John",
"fullName":"John Johnson",
"id":"1234",
"provider":"github"
},
"stars":0,
"updatedAt":"2014-09-03T22:30:21.363Z", // THIS HAS BEEN UPDATED
"createdAt":"2014-09-03T22:10:05.679Z",
"links":[
{
"url":"http://www.newurl.com", // THIS HAS BEEN ADDED
"title":"New Url!",
"description":"Yep, definitely a new URL!",
"_id":"9413967d017c7988022579ba"
},{
"url":"http://www.duck.com",
"title":"Ducks!",
"description":"Nope, no ducks",
"_id":"5407967d017c7988022579ba"
}
]
};
On error, returns null.
'GET to /api/collection/:url'A request to:
http://localhost:3000/api/collection/anewcollection
Returns a collection data object:
{
"__v":0,
"_id":"540791bd17e7918007c35f5c",
"description":"I've changed the description.",
"title":"A New Collection",
"url":"anewcollection",
"user":{
"givenName":"John",
"fullName":"John Johnson",
"id":"1234",
"provider":"github"
},
"stars":100,
"updatedAt":"2014-09-03T22:49:01.329Z",
"createdAt":"2014-09-03T22:10:05.679Z",
"links":[
{
"url":"http://www.duck.com",
"title":"Ducks!",
"description":"Nope, no ducks",
"_id":"54079820fa1e5048175724e4"
},{
"url":"http://www.duckduckgo.com",
"title":"Real Ducks",
"description":"Yay",
"_id":"54079820fa1e5048175724e3"
}
]
};
A request to:
http://localhost:3000/api/collection/DoesNotExist
Returns:
null;'GET to /api/user/:userProvider/:userId'
Note: If it is more convenient, this can easily be refactored to return all the collection data, not just the meta data.
A request to:
http://localhost:3000/api/user/github/1234
Returns an ARRAY of collection meta data objects:
Each element of the ARRAY:
{ "_id":"540791bd17e7918007c35f5c",
"description":"I've changed the description.",
"title":"A New Collection",
"url":"anewcollection",
"user":{
"givenName":"John",
"fullName":"John Johnson",
"id":"1234",
"provider":"github"
},
"stars":100
}
A request to:
http://localhost:3000/api/user/NoSuchProvider/NonExistentUser
Returns an empty array
[]'GET to /api/all'
This will probably be impracticable if the db gets to be a good size
A request to: 'http://localhost:3000/api/all' Returns an ARRAY of collection meta data objects.
Each element of the returned ARRAY:
{"_id":"540629a19850458c1ec42c60",
"description":"Angular Tutorials",
"title":"Angular",
"url":"angular",
"user":{
"givenName":"Oslo",
"fullName":"Oslo Bar",
"id":"Oslo",
"provider":"test"
},
"stars":0
},{
"_id":"54065ce927cc69d4045015e4",
"description":"The cutest",
"title":"Puppies",
"url":"puppies",
"user":{
"provider":"test",
"fullName":"Oslo",
"id":"Oslo",
"givenName":"Oslo"
},
"stars":0
}