API documentation

wvengen edited this page Dec 14, 2015 · 3 revisions

This page describes Open Food Network's API. It is based on Spree's API, which has extensive documentation (source). See also spree-api's routes.rb.

The Open Food Network API is not finished. Entries that are crossed out are candidates for addition.

Quick links

Spree

Open Food Network

Authorization

To access the API, you need an API key. This can be found in the admin backend at the right of the edit user page. That can be passed with the X-Spree-Token header, or the token parameter. Read more.

If you want to verify programmatically that you have a valid token, the /api/users/authorise_api endpoint will return on success:

{
    "success": "Use of API Authorised"
}

Enterprises

  • GET /api/enterprises - returns a list of all enterprises
  • GET /api/enterprises/managed - returns a list of enterprises the user manages
  • GET /api/enterprises/accessible - returns a list of the user has access to
  • POST /api/enterprises - creates a new enterprise
  • PUT /api/enterprises/:id - updates an enterprise
  • DELETE /api/enterprises/:id - deletes an enterprise

GET /api/enterprises/managed

Returns a list of enterprises the user manages.

[
  {
    id: 1,
    name: "Enterprise 1"
  }
  ...
]

Order cycles

GET /api/order_cycles/managed

Returns the list of order cycles of enterprises the user manages.

[
  {
    id: ​1,
    name: "Winter season",
    first_order: "2015-11-01",
    last_order: "2015-12-04",
    suppliers: [
      {
        id: ​2,
        name: "Enterprise 2"
      }
    ],
    distributors: [
      {
        id: ​15,
        name: "The Basket"
      }
    ]
  },
  ...
]

GET /api/order_cycles/accessible

Returns the list of order cycles that are accessible to the user. The optional parameter as can either distributor or producer and will filter the list to the user's distributor- or producer-role respectively.

Additional scopes

In Open Food Network users can manage enterprises, and it can be useful to retrieve a list of enterprises, orders, order cycles and products that the user accessing the api manages. Open Food Network includes an additional scope for those:

  • GET /api/products/managed
  • GET /api/orders/managed
  • GET /api/order_cycles/managed
  • GET /api/enterprises/managed

They work just like the regular index, except filter the results to those the user can manage. The products index has some additional scopes:

  • GET /api/products/bulk_products - products that require group buying
  • GET /api/products/overridable - TODO explain

Soft delete

Products and variants can also be soft-deleted in Open Food Network. This is done with the endpoints

TODO Explain what and why of soft-deletion.

  • DELETE /api/products/:product_id/soft_delete
  • DELETE /api/products/:product_id/variants/:variant_id/soft-delete
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.