DataAPI.md

Data API Specification

This is the main API interface to be used for CRUD on module's data.

It allows Fluidspace environment to handle errors along with displaying appropriate UI status to the user. It parses JSON responses and performs basic validation to ensure your module can interact on data with minimum code.

🔖 Docs Index

• What is Fluidspace?
• Installation Guide
• Module Documentation
• Props API

Constructor

ModuleDataAPI(module_id: string, dataset_id: string): object

Methods

🟣 Fetch Data

Please refer to this link for supported properties in parameters.

fetch(parameters: object): Promise<object>

Response:

{
    _id: string,                            // document id
    _created_on: number,                    // UTC milliseconds
    _last_modified: number,                 // UTC milliseconds
    _created_by: string | object | null,    // user id / resolved user info / null if account deleted>

    page: number,                           // current page, -1 if page unspecified in parameters>
    count: number,                          // num of documents returned
    total_documents: number,                // total documents for the passed parameters
    
    documents: Array                        // returned documents
}

If resolve_creator: true in parameters then response _created_by has resolved user info:

{
    id: string,     // user id
    fname: string,  // creator first name
    lname: string,  // creator last name
    email: string   // creator email address
}

---

🟣 Fetch data from another module (a.k.a. companion)

filtersAndOptions follows the same parameters available for fetch().

fetchFromCompanion(companion_id: string, filtersAndOptions: object): Promise<object>

Response: Same as fetch()

---

🟣 Insert data

insert({ 'documents': Array<object> }): Promise<object>

Response:

• If response is OK

  {
      insert_status: number,              // (0, 1, 2) See below for its meaning
      documents_count: number,            // Number of documents given to insert
      inserted_count: number,             // Number of documents successfully inserted
      inserted_documents: Array<object>   // Inserted Documents
  }

• If insert_status ≠ 1

  {
      insert_status: number,             // (0, 1, 2) See below for its meaning
      error_message: string,              // Small error description
      inserted_documents: Array<object>   // Inserted Documents
  }

• All other types of error shall be handled by Fluidspace environment.

Values for insert_status

insert_status	Meaning
0	HTTP 400 - Required fields are missing HTTP 200 - Operation not performed
1	Successfully inserted the documents
2	No documents provided to insert. Operation not performed

---

🟣 Update data

update({ '_id': string, 'updates': object }): Promise<object>

Response:

• If response is OK

  {
      update_status: number,      // (1, 2, 3) See below for its meaning
      updated_count: number,      // Number of updated documents
      updated_document: object    // Copy of entire document after updating
  }

• If update_status ≠ 1

  {
      update_status: number,      // (1, 2, 3) See below for its meaning
      error_message: string      // Small error description
  }

• All other types of error shall be handled by Fluidspace environment.

Values for update_status

update_status	Meaning
1	Successfully updated the document.
2	Incomplete request, missing required fields. Operation not performed.
3	Invalid document identifier (_id)

---

🟣 Delete data

delete(ids_to_delete: Array<string>): Promise<object>

Response:

• If response is OK

  {
      delete_status: number,      // (1, 2) See below for its meaning
      deleted_count: number,      // Number of deleted documents
      deleted_ids: Array<string>  // IDs of deleted documents
  }

• If delete_status ≠ 1

  {
      delete_status: number,      // (1, 2) See below for its meaning
      error_message: string,      // Small error description
      deleted_ids: Array<string>  // IDs of deleted documents
  }

• All other types of error shall be handled by Fluidspace environment.

Values for delete_status

delete_status	Meaning
1	Successfully deleted the document.
2	No document ids provided to delete. Operation not performed.

⛔️ General Errors

Fluidspace environment automatically handles the following errors:

• HTTP 401 (Invalid user session)
• HTTP 500 (internal server error)
• Network error
• JSON parsing error

A more graceful Error will be thrown to the API caller so, make sure to .catch() in all the API requests and handle them appropriately at the module level.

The message "PARSING_ERROR" or "NETWORK_ERROR" can be expected in error.message property in catch():