API documentation

Version 0.10 (23/11/2022)

Base URL: https://api-snapearth.isardsat.space/

Authentication

Except where otherwise noted, all calls to the EarthFoodSecurity API require authentication, provided by Firebase Authentication. API clients can use one of the available versions of the Firebase Authentication client: iOS, Android, web/Node.js (firebase module in npm), C++, Unity.

To configure Firebase Authentication for EarthFoodSecurity:

const { initializeApp } = require("firebase/app");
const { getAuth, signInWithEmailAndPassword } = require("firebase/auth");

initializeApp({
  apiKey: 'AIzaSyBxz3c_G0A-_4YdKAfplCy6ZSYWkhoo3HY',
  authDomain: 'snapearth-7d3c3.firebaseapp.com',
  projectId: 'snapearth-7d3c3',
  storageBucket: 'snapearth-7d3c3.appspot.com',
  messagingSenderId: '1014088494857',
  appId: '1:1014088494857:web:60b38dd578bc9fd0afedd8',
});

To sign in, use the email and password method:

const auth = getAuth();
await signInWithEmailAndPassword(auth, email, password);

After sign-in, you’ll need an ID token to use the EarthFoodSecurity API:

const token = await auth.currentUser.getIdToken();

Tokens are short-lived (1 h), so make sure to get a new token before the old one expires. There are multiple ways to do it, but probably the simplest one is to force generation of a new token with a periodicity slightly below 1 h:

setInterval(async () => {
  const token = await auth.currentUser.getIdToken(true);
  /* store in local state... */
}, 55 * 60e3);

Make sure to include a valid ID token in the Authorization header of all calls to the API:

Authorization: Bearer <token>

API responses

JSON is used in the body of API requests and responses. Errors returned by the API are also in JSON format.

Successful requests return a 200 status code. The response body is formatted in JSON and has the form:

• Singular endpoints (e.g. /api/:version/me):

  {
    "result": {
      // ...
    }
  }

• Plural endpoints (e.g. /api/:version/jobs):

  {
    "results": [
      {
        // ...
      },
      {
        // ...
      },
      {
        // ...
      }
    ]
  }

Failed requests return a status code following convention (3xx for redirections, 4xx for client errors, 5xx for server errors). The response body is formatted in JSON and has the form:

{
  "errorHttpStatusCode": 400,
  "errorCode": "INVALID_QUERY",
  "errorDescription": "Detailed description"
}

Endpoint versions

Most endpoint URLs have the form /api/:version/.... The version parameter is related to a set of guaranteed query parameters and result attributes. Legal version values and whether they are deprecated are included in the endpoint documentation.

New query parameters or result attributes may be added without affecting the endpoint version, but not removed. Versions -v0 are an exception to this rule.

Note: The general EarthFoodSecurity API version (X.Y) may change due to bug fixes or additional response attributes without affecting endpoint versions.

Other API aspects

All dates are formatted in ISO8601, UTC time.

Data entities

Users

Jobs

Job statuses

Job outputs

Endpoints

GET /api/:version/me

Returns the currently logged-in User.

Versions: web-v0

Query options: none.

GET /api/:version/jobs/

Returns a list of the existing jobs (in summary view) for the current user.

Versions: web-v0

Query options: none.

GET /api/:version/job/:id

Returns a detailed view of the job specified by ID.

Versions: web-v0

Query options: none.