-
Notifications
You must be signed in to change notification settings - Fork 16
Mongo Server API
{
title: String,
url: String,
description: String,
stars: Number,
user: {
provider: String,
id: String,
fullName: String,
givenName: String
},
links: [
{
url: String, // external url of the link
title: String,
description: String
},{
// More links here...
}
]
}
url is the title scraped of invalid url characters. It is a relative link. Currently with angular implementation:
domain.com/#/:url
user object is roughly modeled after passport user profile
Note: the value of the user property is currently populated by the userManagement Factory:
$scope.collection.user = userManagement.user;
Postman url to import example requests: 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"
}
]
};
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",
"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
}
]
};
On error, returns null.
If there is an error, it might be because there is another collection with the same url. The server enforces unique urls.
POST to /api/collection/update
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
}
]
};
On success, returns a collection data object with the updated fields
{
"__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"
}
]
}
On error, 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 done 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
POST to /api/collection/addLink
Data should be a JSON object with the collection _id of the target collection and an ARRAY of link(s) to be added:
{
"_id":"540791bd17e7918007c35f5c",
"link":[{
"url":"http://www.newurl.com",
"title":"New Url!",
"description":"Yep, definitely a new URL!"
}
]
}
On success, returns updated 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
}