• Accessing the API
• Responses
  • Success Responses
  • Error Responses
  • Images
• Endpoints
  • GET /products
  • GET /products/:productId
  • POST /orders
  • GET /orders/:orderId

The API is available at [domain]/api, like localhost:7000/api or http://myapp.heroku.com/api. You should create an API client for accessing the API. The API only accepts JSON bodies for POSTing, so don't try to send form data to it. Likewise, GET requests only accept query parameters.

All of the endpoints below should be prefixed with the URL. So /products would be accessed at localhost:7000/api/products or http://myapp.heroku.com/api/products.

Responses from the API only come in two flavors, successful ones, and errorous ones. The response is always a JSON object that has the same shape, depending which of the two it is.

Any 2XX response means everything went OK. It'll always have this shape, a lone data key:

{
  data: {
    /* ... */
  },
}

Data could have any number of keys in it, but it'll always be an object.

Any 4XX or 5XX response means something went wrong. It'll always have this shape, a lone error key:

{
  error: {
    code: 500, // The code of the response, 4XX or 5XX
    type: "SOME_ERROR", // A developer-readable error "type"
    message: "Something went wrong!", // A user-readable error message
    data: { /* ... */ }, // OPTIONAL: Some data about what went wrong
  }
}

Any of the images listed below have the following shape:

{
  small: "http://url.to/image-small.jpg",
  medium: "http://url.to/image-small.jpg",
  large: "http://url.to/image-small.jpg",
  original: "http://originalurl.com/whateverisintheform.jpg"
}

• small - Max dimension of 160px
• medium - Max dimension of 400px
• large - Max dimension of 800px
• original - URL to the original source image, avoid using if possible

Gets all products, with optional sort and search parameters. Only gets a subset of the product, so you'll need to fetch the individual product to display all of it.

{
  data: {
    products: [{
      name: "Name of Product",
      price: "29.98",
      category: "category", // Not always here!
      rating: 9, // Out of 10, not always here!
      image: { /* Typical image... */ } // Guaranteed to be here
    }, /* ... */],
  }
}

• DB_ERROR (500) - Only if something really bad happens to the DB

Fetch a particular product. Comes with all of the products information.

{
  data: {
    product: {
      name: "Name of Product",
      price: "29.98",
      category: "category", // Not always here!
      rating: 7, // Out of 10, not always here!
      description: "The full length description of the product", // Not always here!
      images: [/* Array of image(s)... */],
      specs: [{
        label: "Label",
        value: "Value"
      }, /* ... */] // Guaranteed array, but might be empty!
    }
  }
}

• BAD_PARAM (400) - If an invalid product ID is sent (like a product doesn't exist)
• DB_ERROR (500) - Only if something really bad happens to the DB

Create a new order given a set of products, and some information about who to ship it to. Creates a new order and returns just the ID to you. You can later fetch the whole order

{
  data: {
    orderId: "835137951"
  }
}

• BAD_PARAM (400) - If any invalid fields are sent, data will be an array of { field: "address", error: "Address is required" } if you want to show detailed errors
• DB_ERROR (500) - Only if something really bad happens to the DB

Fetch a created order.

{
  data: {
    order: {
      products: [/* List of products, identical to GET `/products` */],
      name: "John Smith",
      address: "1122 Lane Ave",
      address2: "Apt 209", // Not always there
      city: "New York",
      state: "NY",
      zipcode: "10001",
      createdAt: "2017-08-12 18:32:50.005",
    }
  }
}

• BAD_PARAM (400) - If an invalid order ID is sent (like an order doesn't exist)
• DB_ERROR (500) - Only if something really bad happens to the DB