Common API guide

Swagger UI for API access

How to authenticate in swagger ui, refer to authentication in swagger ui.

Common API request headers / query params

KEY	Location	Desc
x-refresh	Header, Query	Get entity by id or throw HTTP 404 if not found

Common API response headers

HEADER	Desc
x-error-code	Indicate more error detail in addition to HTTP status code, for example, incase of access token expires HTTP code is 401, and x-error-code is access-token-expired

Common entities management (CRUD)

Entity objects

// Single entity object
interface Entity {}

// Entity list object
interface EntityList<Entity> {
  // Total entity count
  totalCount?: number;

  // In fast counting, totalCount value is limited, use this value to indicate if the actual totalCount is larger than return totalCount
  hasMoreCount?: boolean;

  // Current data offset in full data set
  offset?: number;

  // Current data limit
  limit?: number;

  // Is has next data with current offset and limit, use in paging
  hasNext?: boolean;

  // Actual entity data list
  items?: Entity[];
}

Parameters objects

// Entity create payload
interface EntityCreateDto {
  // Data depend on entity data
  [key: string]: any;
}

// Entity update payload
interface EntityUpdateDto {
  // Data depend on entity data
  [key: string]: any;
}

// Entity query parameter
interface EntityQuery {
  // Detail filter object
  filter?: EntityFilter;

  // Select return field, ex [ 'id', 'name' ]
  selector?: string[];

  // Ordering by fields 1 (ASC) or -1 (DESC), ex { id: 1, name: -1 }
  sort?: Record<string, 1 | -1>;

  // Include soft deleted data
  withDeleted?: boolean;

  // Include fast total count in the query, the value is limited for fast query, use with hasMoreCount to check if there is more values
  withFastTotalCount?: boolean;

  // Include real total count in the query, this can be expensive operation
  withTotalCount?: boolean;

  // Limit the number of entities return
  limit?: number;

  // Select entities begin from skip
  skip?: number;
}

// Entity filter parameters
interface EntityFilter {
  // Mix of condition query like mongo https://www.mongodb.com/docs/manual/tutorial/query-documents/
  // Support: $and, $or, $not, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $like, $nlike, $ilike, $notilike, $isnull, $notnull, $regex, $iregex,
  // Note: not all of entity fields are queriable, only fields selected by API developers can be put as query fields
  // What fields are selected also depend on each entity, please consults the entity document for more info
  [key: string]: any;
}

export interface EntityDeleteResult {
  // How many entities deleted
  affected: number;

  // Ids of entities
  ids?: string[];

  // Id of entity
  id?: string;
}

Get one

VERD	Endpoint	Parameters	Response	Desc
GET	/api/{entities}/:id	None	Entity	Get one entity by id, throw HTTP 404 if not found
POST	/api/{entities}/get-one	EntityQueryArgs	Entity	Get one entity by using query object, throw HTTP 404 if not found

Get many

VERD	Endpoint	Parameters	Response	Desc
GET	/api/{entities}	None	Entity[]	Get all entities, internal limit is 1000

Find one

VERD	Endpoint	Parameters	Response	Desc
POST	/api/{entities}/find-one/:id	None	Entity or null	Find one entity by id, return null if not found
POST	/api/{entities}/find-one	EntityQuery	Entity or null	Find one entity by using query object, return null if not found
POST	/api/{entities}/find-one-by	EntityFilter	Entity or null	Find one entity by using filter object, return null if not found

Find many

VERD	Endpoint	Parameters	Response	Desc
POST	/api/find-many	EntityQuery	Entity[]	Find many entities by using query object
POST	/api/find-many-by	EntityFilter	Entity[]	Find many entities by using filter object
POST	/api/find-many-by-ids	{ ids: string[]}	Entity[]	Find many entities by using id list
POST	/api/find-many/list	EntityQuery	EntityList	Find many entities as list by using query object

Create one

VERD	Endpoint	Parameters	Response	Desc
PUT	/api/{entities}	EntityCreateDto	Entity	Create one entity
POST	/api/{entities}/create-one	EntityCreateDto	Entity	Create one entity

Create many

VERD	Endpoint	Parameters	Response	Desc
POST	/api/{entities}/create-many	{ items: EntityCreateDto[] }	Entity[]	Get all entities, internal limit is 1000

Save one

VERD	Endpoint	Parameters	Response	Desc
POST	/api/{entities}/save-one	EntityCreateDto	Entity	Create or update an entity, if update parameter must include id field

Save many

VERD	Endpoint	Parameters	Response	Desc
POST	/api/{entities}/save-many	{ items: EntityCreateDto[] }	Entity[]	Create or update many entities, if update parameter must include id field

Update one

VERD	Endpoint	Parameters	Response	Desc
PATCH	/api/{entities}/:id	EntityUpdateDto	Entity	Update one entity by id
POST	/api/{entities}/update-one/:id	EntityUpdateDto	Entity	Update one entity by id

Update many

VERD	Endpoint	Parameters	Response	Desc
POST	/api/{entities}/update-many-by-ids	{ items: { ids: string, updateDto: EntityUpdateDto }[] }	Entity[]	Update many entities

Delete one

VERD	Endpoint	Parameters	Response	Desc
DELETE	/api/{entities}/:id		EntityDeleteResult	Delete one entity by id
POST	/api/{entities}/delete-one/:id		EntityDeleteResult	Delete one entity by id

Delete many

VERD	Endpoint	Parameters	Response	Desc
POST	/api/{entities}/delete-many-by-ids	{ ids: string[] }	EntityDeleteResult	Delete many entities by id