Skip to content

Instantly share code, notes, and snippets.

@BeattieM

BeattieM/API Contract Example Spec.md

Last active April 17, 2024 14:29
Show Gist options
  • Star 63 You must be signed in to star a gist
  • Fork 22 You must be signed in to fork a gist
  • Save BeattieM/324063512d166122ba5c to your computer and use it in GitHub Desktop.
Save BeattieM/324063512d166122ba5c to your computer and use it in GitHub Desktop.
Download ZIP
An example of an API contract between the server and front-end devices
Raw
API Contract Example Spec.md

#Users

  • User object
{
  id: integer
  username: string
  email: string
  created_at: datetime(iso 8601)
  updated_at: datetime(iso 8601)
}

GET /users

Returns all users in the system.

  • URL Params
    None
  • Data Params
    None
  • Headers
    Content-Type: application/json
  • Success Response:
  • Code: 200
    Content:
{
  users: [
           {<user_object>},
           {<user_object>},
           {<user_object>}
         ]
}

GET /users/:id

Returns the specified user.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content: { <user_object> }
  • Error Response:
    • Code: 404
      Content: { error : "User doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

GET /users/:id/orders

Returns all Orders associated with the specified user.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content:
{
  orders: [
           {<order_object>},
           {<order_object>},
           {<order_object>}
         ]
}
  • Error Response:
    • Code: 404
      Content: { error : "User doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

POST /users

Creates a new User and returns the new object.

  • URL Params
    None
  • Headers
    Content-Type: application/json
  • Data Params
  {
    username: string,
    email: string
  }
  • Success Response:
  • Code: 200
    Content: { <user_object> }

PATCH /users/:id

Updates fields on the specified user and returns the updated object.

  • URL Params
    Required: id=[integer]
  • Data Params
  {
  	username: string,
    email: string
  }
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content: { <user_object> }
  • Error Response:
    • Code: 404
      Content: { error : "User doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

DELETE /users/:id

Deletes the specified user.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
    • Code: 204
  • Error Response:
    • Code: 404
      Content: { error : "User doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

#Products

  • Product object
{
  id: integer
  name: string
  cost: float(2)
  available_quantity: integer
  created_at: datetime(iso 8601)
  updated_at: datetime(iso 8601)
}

GET /products

Returns all products in the system.

  • URL Params
    None
  • Data Params
    None
  • Headers
    Content-Type: application/json
  • Success Response:
  • Code: 200
    Content:
{
  products: [
           {<product_object>},
           {<product_object>},
           {<product_object>}
         ]
}

GET /products/:id

Returns the specified product.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content: { <product_object> }
  • Error Response:
    • Code: 404
      Content: { error : "Product doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

GET /products/:id/orders

Returns all Orders associated with the specified product.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content:
{
  orders: [
           {<order_object>},
           {<order_object>},
           {<order_object>}
         ]
}
  • Error Response:
    • Code: 404
      Content: { error : "Product doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

POST /products

Creates a new Product and returns the new object.

  • URL Params
    None
  • Data Params
  {
    name: string
    cost: float(2)
    available_quantity: integer
  }
  • Headers
    Content-Type: application/json
  • Success Response:
  • Code: 200
    Content: { <product_object> }

PATCH /products/:id

Updates fields on the specified product and returns the updated object.

  • URL Params
    Required: id=[integer]
  • Data Params
  {
  	name: string
    cost: float(2)
    available_quantity: integer
  }
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content: { <product_object> }
  • Error Response:
    • Code: 404
      Content: { error : "Product doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

DELETE /products/:id

Deletes the specified product.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
    • Code: 204
  • Error Response:
    • Code: 404
      Content: { error : "Product doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

#Orders

  • Order object
{
  id: integer
  user_id: <user_id>
  total: float(2)
  products: [
              { 
                product: <product_id>,
                quantity: integer 
              },
              { 
                product: <product_id>,
                quantity: integer 
              },
              { 
                product: <product_id>,
                quantity: integer 
              },
            ]
  created_at: datetime(iso 8601)
  updated_at: datetime(iso 8601)
}

GET /orders

Returns all users in the system.

  • URL Params
    None
  • Data Params
    None
  • Headers
    Content-Type: application/json
  • Success Response:
  • Code: 200
    Content:
{
  orders: [
           {<order_object>},
           {<order_object>},
           {<order_object>}
         ]
}

GET /orders/:id

Returns the specified order.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content: { <order_object> }
  • Error Response:
    • Code: 404
      Content: { error : "Order doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

GET /orders/:id/products

Returns all Products associated with the specified order.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content:
{
  products: [
           {<product_object>},
           {<product_object>},
           {<product_object>}
         ]
}
  • Error Response:
    • Code: 404
      Content: { error : "Order doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

GET /orders/:id/user

Returns all Users associated with the specified order.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response: { <user_object> }
  • Error Response:
    • Code: 404
      Content: { error : "Order doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

POST /orders

Creates a new Order and returns the new object.

  • URL Params
    None
  • Data Params
  {
  	user_id: <user_id>
  	product: <product_id>,
  	quantity: integer 
  }
  • Headers
    Content-Type: application/json
  • Success Response:
  • Code: 200
    Content: { <order_object> }

PATCH /orders/:id

Updates fields on the specified order and returns the updated object.

  • URL Params
    Required: id=[integer]
  • Data Params
  {
  	product: <product_id>,
  	quantity: integer 
  }
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
  • Code: 200
    Content: { <order_object> }
  • Error Response:
    • Code: 404
      Content: { error : "Order doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }

DELETE /orders/:id

Deletes the specified order.

  • URL Params
    Required: id=[integer]
  • Data Params
    None
  • Headers
    Content-Type: application/json
    Authorization: Bearer <OAuth Token>
  • Success Response:
    • Code: 204
  • Error Response:
    • Code: 404
      Content: { error : "Order doesn't exist" }
      OR
    • Code: 401
      Content: { error : error : "You are unauthorized to make this request." }
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment