API Requests

There are two Corva APIs:

1. Corva API Swagger
2. Corva Data API Swagger
3. Corva Data API

@corva/ui package provides public methods for making asynchronous requests. Methods are: get, post, put, patch, del. The signature is the same for both APIs.

What corvaAPI and corvaDataAPI are.

Both corvaAPI and corvaDataAPI are javascript objects which provide access to asynchronous functions . Functions are: get , post, patch, put and del . Function names correspond to HTTP request methods (del stands for delete).

Overview:

import { corvaAPI, corvaDataAPI } from '@corva/ui/clients';
/* later in the code */
const apiResponse = await corvaAPI.post(path, entity);
const dataApiResponse = await corvaDataAPI.get(path, queryParams);

Functions signature:

/**
* The get method is used to **read** (or retrieve) a representation of a resource
* @async
 * @param {string} path - path to resource.
 * @param {Object=} queryParams - Object with query params such as per_page, sort, asset_id, etc.
 * @returns {Promise<*>}
 */
async function get(path, queryParams={})

/**
* The post method is most-often utilized to **create** new resources.
* @async
 * @param {string} path - path to resource.
 * @param {Object|Array} entity - API entity/entities to create
 * @returns {Promise<*>}
 */
async function post(path, entity)

/**
* The put method is used to create/update a resource. All fields must be provided in p
* @async
 * @param {string} path - path to resource.
 * @param {Object} entity -API entity to update/create
 * @param {Object=} queryParams - Object with query params such as fields.
 * @returns {Promise<*>}
 */
async function put(path, content, queryParams)

/**
* del is used to **delete** a resource identified by a URI or to **delete** resources that match criteria provided in a query.
* @async
 * @param {string} path - path to resource.
 * @param {Object=} queryParams - Object with query params. Optional, can be used to identify query with matching criteria
 * @returns {Promise<*>}
 */
async function del(path, queryParams={})

How to use corvaAPI and corvaDataAPI

Quick Corva API example:

import Jsona from 'jsona'; // For deserializing api response
import { corvaAPI } from '@corva/ui/clients';
const dataFormatter = new Jsona(); // NOTE: data formatter is required for data deserialization

async function fetchRigWells(rigId) {
  try {
    // NOTE: Only fields provided in "fields" key will be returned. Use it

    const response = await corvaAPI.get(`/v2/wells`, {
      limit: 100, // NOTE: Fetch up to 100 wells
      sort: 'name', // NOTE: Sort wells by name
      rig: rigId,
      // NOTE: Include only these fields in response.
      // If "fields: all" is applied then all fields will be returned
      fields: ['well.name', 'well.id'], //NOTE: The field key values need to be an array of strings.
    });

    // NOTE: Deserialize api response. Optional step
    const deserializedResponse = dataFormatter.deserialize(response);

    return deserializedResponse;
  } catch (e) {
    // handle error
  }
}

Quick Corva DATA API example:

import { corvaDataAPI } from '@corva/ui/clients';

async function fetchWellSections(assetId) {
  try {
    const response = await corvaDataAPI.get(
      `/api/v1/data/corva/data.well-sections/`,
      {
        limit: 20, // NOTE: Fetch up to 20 well sections
        skip: 0, // NOTE: Required for pagination
        // NOTE: Make sure the sort field hit database indexes. Otherwise the request will take too long. Sort of -1 returns the latest first.
        sort: JSON.stringify({ 'data.top_depth': -1 }), // expected a valid json string
        query: JSON.stringify({ asset_id: assetId }), // expected a valid json string
        // NOTE: To make efficient request - fetch only needed fields
        fields: ['data.name', 'data.diameter', 'data.top_depth'].join(','), //NOTE: The field key values need to be a string.
      }
    );

    return response;
  } catch (e) {
    console.log(e);
  }
}

Additional resources:

• Corva API documentation
• Corva DATA API documentation
• React useState hook
• React useEffect hook
• MongoDB docs

General recommendations:

1. Try to fetch ONLY data you need.
   • Use skip/limit in datasets and page/per_page for pagination when making get requests;
   • Use fields key to get only fields required for your app;
   • Filter data on API side by providing queries.
2. Wrap all api requests in try/catch blocks to make your app more stable and provide better UX. Show loading states and error messages when sending api requests
3. Send api requests in react effects. Make sure you're familiar with React hooks concept (in particular with (3) and (4)).
4. Make sure you use both trailing and leading slashes in your requests.