Designing an API

[draganczukp]

It would be nice to have a lesson about designing and maybe creating an API. Maybe with some examples of good and bad APIs.

One example you could use would be a fictional API for a stock keeping service, that would allow for things like checking and updating an amount of a product, adding and removing products etc.

An example of a good API definition

GET /api/v1/storages/by-id/[storage id]/products #lists all products in a specific storage. Results: 200 and JSON array of products or 404 if no storage with id [storage id] exists
GET /api/v1/storages/by-id/[storage id]/products/by-id/[product id] #shows all information about a specific product in a specific storage. Results: 200 and JSON object describing the product or 404 if no storage or product with a specified id exists
# Similar thing could be done for using just the name of a storage instead of and id by changing by-id to by-name
POST /api/v1/storages/new # creates a new storage. Request body: JSON object describing the new storage (things like name, location etc.). Results: 201 and an id of the created storage, 400 and JSON array of all errors if the body has some elements missing or 403 if the user is not allowed to create new storages
POST /api/v1/storages/by-name/[storage name]/products/add # adds a product(s) to storage. Request body: JSON array with products to add in an object containing the id of a product and the count. Results: 200 if everything was added, 400 if something was wrong with the request and 403 if user doesn't have permission for that
PATCH /api/v1/storages/by-id/[storage id]/products/by-id/[product id] # modifies a product in storage. Request body: JSON object with fields and values that will be overridden in the product. Results: 200 on success, 404 if either storage or product doesn't exist and 403 if user doesn't have permission for that 

An example of a bad API definition: All routes use only GET and and always return 200, even if there was an error. The result is always a JSON object that look like this:

{
    "error": true,
    "body": {
        "code": 404,
        "message": "Not found"
    }
}

Routes:

GET /getStorageById/[storage id]/getAllProducts # Returns all products
GET /getStorageById/[storage id]/getProductById/[product id] # Return a specific product
GET /createNewStorage/[storage name]/[storage location/[etc.] # Creates a new storage
GET /getStorageById/[storage id]/addNewProductToStorage/[product id]/[count] # adds a product to storage with specified count
GET /getStorageById/[storage id]/updateProductCount/[product id]/[count] # Changes the count of product

[shiffman]

I do like this idea and have made videos on it before! https://shiffman.net/a2z/node-api/ Unfortunately I think this is out of the scope of what the mission is for this course. (Though I agree it's a great topic for a course!)

[shiffman]

Oh, also take a look at this example / tutorial from @joeyklee!

https://github.com/joeyklee/simple-express-api

I think elements will come in about this for the two "full stack" scenarios in #12. Thank you!