API Usage

Making a query directly to the API is a three-stage process. First, you use your credentials to acquire a JSON Web Token that you can save and use for one hour. Once the token expires, you will need to request a fresh token.

Second, that token needs to be passed in an authorization header to subsequent POST requests to the API as demonstrated in the following javascript code:

  
  async function queryAPI() {

  // Get Auth Token
  const rootUrl = 'https://maqi-api.astro.umd.edu';
  const username = '[USERNAME]';
  const password = '[PASSWORD]';

  const response = await fetch(rootUrl + '/api/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(authData),
  });

  const authStatus = response.status;
  const data = await response.json();
  if (authStatus !== 200) {
    console.log('Authentication failed: ', data);
    return;
  }
  const token = data.token;


  // Use token to make a query
  const dataResponse = await fetch(rootUrl + '/api/query', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ query: 'SELECT * FROM mpc_orbits LIMIT 10;' }),
  });

  const data2 = await dataResponse.json();
  console.log(response2.status, JSON.stringify(data2, null, 2));
}

queryAPI();
  

When the query is submitted, it is put onto a queue, and the response from the http request to the endpoint `/api/query` is a JSON object with meta data related to the query:

  
  
  {
    "job_id": "admin-1734396461.6923933-46247c4fe6fb17eff4ade944644f877c0c3ede1c7a7b3c736cd6a00e9bc7857b",
    "query": "SELECT * FROM mpc_orbit LIMIT 100;",
    "status": "queued",
    "creation_time": "1734396461.6924212",
    "error_message": null
  }

  

As the query is processed, the status of the query will get updated, and will end on either 'success' or 'error'. In the event of success, the results of the query will be posted, and the url included in the meta datum.