documentation.js

// Collection Schema:
{
  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 authientication system
    fullName: String,
    givenName: String
  },
  links: [
    { 
      url: String, // external url of the link
      title: String,
      description: String
    } // More links here...
  ]
}

// Note: Nothing in the API is set in stone. If anyone has any suggestions to
// make it better, more convient, or any other feedback on it, please express it.
// Thanks.

// Postman link to example queries:
'https://www.getpostman.com/collections/478b3030a71770ebf8c4'

// Endpoints:
'--------------------------------------------------------------';

'POST to /api/collection/create';
// Create a new collection

// Example POST data:
{
  "title": "A New Collection",
  "description": "So many good links",
  "user": { // populated by userManagement Factory
    "provider": "github",
    "id": "1234",
    "fullName": "John Johnson",
    "givenName": "John"
  },
  "links": [
    {
      "url": "http://www.duck.com",
      "title": "Ducks!",
      "description": "So one might think"
    }
  ]
};

// Note: the user data is currently populated by the userManagement Factory:
$scope.collection.user = userManagement.user;

// On success, returns a collection data object:
{
  "__v":0, // This is the model version generated by mongoose (it can ignore it for our current objectives)
  "_id":"540791bd17e7918007c35f5c", // This is the unique collection id generated by MongoDB. Very useful for doing fast lookups
  "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
    }
  ]
};

// Example failed create. This is probably due to another collection with the same url
// The server enforces unique urls
null;


'--------------------------------------------------------------';

'POST to /api/collection/update';
// Updates a collection

// This endpoint is flexible on its inputs. If you'd like, you can have the client edit 
// the actual collection object and send the entire object (don't have to worry about diffs).

// Example:
{  
  "_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",
  "description":"I've changed the description.", // 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",
  "createdAt":"2014-09-03T22:10:05.679Z", // THIS HAS BEEN UPDATED
  "links":[
    {
      "url":"http://www.duck.com",
      "title":"Ducks!",
      "description":"Nope, no ducks", // THIS HAS BEEN UPDATED
      "_id":"5407967d017c7988022579ba"
    }
  ]
};

// If the update fails, it returns null

// It is also possible to just send the data you would like to update
// Here we are just adding a link.
{  
  "_id":"540791bd17e7918007c35f5c",
  "links": [
    {
      "url": "http://www.duck.com",
      "title": "Ducks!",
      "description": "Nope, no ducks"
    },
    {
      "url": "http://www.duckduckgo.com",
      "title": "Real Ducks",
      "description": "Yay"
    }
  ]
}
// Currently, the only way to add a link is with an update. High on the 
// todo list is an endpoint to add a link directly.

// 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 since the client should have the id
// so this will not likely ever be used.
{ 
  "title":"A New Collection",
  "stars": 100
}

// Note: Currently there is no validation on updates. This is on the todo.
// We must enforce no updates to immutable fields!

var immutableFields = [
  "_id",
  "title",
  "url",
  "user",
  "__v"
]; // The user should not be allowed to change these fields

'--------------------------------------------------------------';

'POST to /api/collection/addlink';
// Add a link to a collection

// Expects data of a specific format.
// Data must have an _id property refering to the target collections _id
// and a links property refering to an array of links to add to the 
// collection
{
  "_id":"5405f70e23089aac14e47c53",
  "links": [
    {
      "url": "http://www.google.com",
      "title": "A duck alternative",
      "description": "Why no ducks?"
    }
  ]
}

// Returns an updated collection data object


'--------------------------------------------------------------';

'GET to /api/collection/:url';
// Retrieves a collection

// 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';
// Retrieves the meta data for all the users collections
// Note: if it is more convenient, this can 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:
[
  {
    "_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
  }
  // There would be more collections here if this example user had more collections
];

// A request to:
'http://localhost:3000/api/user/NoSuchProvider/NonExistentUser'
// Returns an empty array:
[];


'--------------------------------------------------------------';

'GET to /api/all';
// Retrieves the meta data for all collections in the db
// This will probably be impractable 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:
[
  {
    "_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
  }
];