Mongo Server API

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

Endpoints:

Create a new collection

'POST to /api/collection/create';

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 value of the user property 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 (can ignore for our purposes)
  "_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
    }
  ]

};

// Return value if error: null;

// Example of failure, where there is another collection with the same url // The server enforces unique urls

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

Updates a collection

'POST to /api/collection/update'

// This endpoint is flexible on its inputs. You may only include properties where their values have changed. Alternatively, you can send the entire collection object by where the client edit the actual collection object.

// 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",
  "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 error, 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"
    }
  ]

}

// 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!

immutableFields:

  ["_id": id,
  "title": title,
  "url": url,
  "user": user,
  "__v": versionMongoose]; 

// The user should not be allowed to change these fields

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

Adding 1 link to a collection - route used by chrome extension

POST to /api/collection/addLink

Data required: JSON object of the collection id and meta data of link to be added in an array: Example: {

  "_id":"540791bd17e7918007c35f5c",
  "link":[{
      "url":"http://www.newurl.com",
      "title":"New Url!",
      "description":"Yep, definitely a new URL!"
   }]

}

If 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"
     }
  ]

};

If error, returns ?????????

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

Retrieves a collection

'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;

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

Retrieves the meta data for all the users collections

'GET to /api/user/:userProvider/:userId'

// 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:

Each element of 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.

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

Retrieves the meta data for all collections in the db

'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 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
  }