foodsoft/doc/API.md

Foodsoft API

Foodsoft provides a JSON REST API that gives access to operations like like listing open orders, updating the ordergroup's order, and listing financial transactions. Not all Foodsoft functionality is available through the API, but we're open for new additions.

The API is documented using Open API 3.0.1 / Swagger in swagger.yaml. This provides a machine-readable reference that is used to provide documentation. It is generated by rswag wich also provides api-tests. It can be generated running RAILS_ENV=test rails rswag.

Note: the current OAuth scopes may be subject to change, until the next release of Foodsoft.

API endpoint documentation

>> View API documentation <<

The above documentation can communicate with the API directly on a local development installation of Foodsoft at http://localhost:3000/f.

You'll need to give access to the application first. This can be done by going to Administration > Configuration > Apps in Foodsoft. Select New Application, enter any name, put http://petstore.swagger.io/oauth2-redirect.html in Redirect URI and disable Confidential. After submission, you will have an Application UID that you can enter that as client_id after clicking Authorize in the Swagger UI.

Security

Uses the Doorkeeper gem, which provides an OAuth2 provider.

Authorization code flow

This is the recommended flow for server-side web applications, where members login with Foodsoft, then redirected to the app, which then obtains an access token using the authorization code supplied at redirection.

Before you can obtain an access token, the client needs to obtain an id and secret. (You can currently skip this for the password credentials flow.) This needs to be done for each Foodsoft scope by an admin.

1. Click on the Apps button at the right in Foodsoft's configuration screen.
2. Click on New application
3. Enter any Name and put the website of your app in Redirect URI and Submit.
4. Click on the new applications' name for the app id and secret.
5. To quickly test, logging into the app, press Authorize.

Note that the user doesn't need to confirm that he is giving the app access to his Foodsoft account by default, since apps can only be created by admins. If you want to change that, see disable skip_authorization in config/initializers/doorkeeper.rb.

Read more.

Implicit flow

This is the recommended flow for client-side web applications. It looks a lot like the authorization code flow, but when redirecting back to the app, the access token is available directly as part of the url fragment (window.location.hash).

This flow also needs to be registered in Foodsoft as in the authorization code flow, but with Confidential disabled. You only need the client_id, not the secret.

note please make sure you understand sections 4.4.2 and 4.4.3 of the OAuth2 Threat Model document before using this flow.

You may find Doorkeeper's implicit_grant_test useful.

Password credentials flow

To obtain a token using a username/password directly, you can do this:

require 'oauth2'
c = OAuth2::Client.new('client_id', 'secret', site: 'http://localhost:3002/f/', authorize_url: 'oauth/authorize', token_url: 'oauth/token')
c.password.get_token('admin', 'secret').token
# => "1234567890abcdef1234567890abcdef1234567890abcdef123456790abcdef1"

Now use this token as value for the access_token when accessing the API, like http://localhost:3002/f/api/v1/financial_transactions/1?access_token=12345...

Read more.

Logout

When the user logs out of Foodsoft, all access tokens are destroyed, except when the token's scope includes offline_access (so offline applications are possible).