Skip to content

Latest commit

 

History

History
188 lines (148 loc) · 6.07 KB

DataAPI.md

File metadata and controls

188 lines (148 loc) · 6.07 KB
Raw

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

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():