API documentation

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

• Products, their properties and Variants;
• Orders, Line items and Checkouts;
• Payments, Shipments and Return authorizations;
• Taxonomies, Addresses, Countries and Zones;
• Stock Locations and Stock movements.

Open Food Network

• Enterprises
• Order cycles
• The managed scope for Products and Orders, Enterprises and Order cycles;
• A soft_delete action on Products and Variants;

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