Semantic API

Appearance

On this page

@semantic-api/api ​

Types ​

Global API ​

Advanced API ​

You shouldn't be using these unless you really know what you're doing.

Description ​

Please head to Description.

Algorithm ​

Please head to Algorithm.

Collection ​

Please head to Collection.

Context ​

A context is an object that is passed down to the endpoint functions. It contains shorthands for acessing the Model (if the resource is a collection), description, session Token, strongely typed references to another collections and algorithms, and more. To create a context use the helper createContext.

ts
export type Context<
  TDescription extends Description=any,
  TCollections extends Collections=any,
  TAlgorithms extends Algorithms=any,
  TAccessControl extends AccessControl<TCollections, TAlgorithms, TAccessControl>=any
> = Omit<Awaited<ReturnType<typeof internalCreateContext>>,
  'resourceName'
  | 'collection'
  | 'collections'
  | 'accessControl'
> & {
  description: TDescription
  model:  CollectionModel<TDescription>
  collection: TCollections[TDescription['$id']]
  collections: TCollections
  functionPath: FunctionPath
  token: DecodedToken<TAccessControl>

  resourceName?: keyof TCollections | keyof TAlgorithms
  request: any
  h: any

  apiConfig: ApiConfig
  accessControl: TAccessControl
}

It also provides the following shorthand functions:

  • log

Used to log an entry to the database with the system collection Log. For detailed usage head to Logging section.

ts
declare const log: (message: string, details?: any) => Promise<Log>
  • validate

Validates an object against a JSON Schema. For detailed usage head to Validation section.

ts
declare const validate: <T>(
    description: Omit<Description, '$id'>,
    what: T,
    required?: (keyof T)[] | null | undefined
) => ReturnType<typeof import('@semantic-api/api').validateFromDescription>
  • limitRate

Validates an object against a JSON Schema. For detailed usage head to Rate limiting section.

ts
declare const limitRate: (params: RateLimitingParams) =>
    ReturnType<typeof import('@semantic-api/api').limitRate>

ContextOptions ​

Options object used to create a Context.

ts
export type ContextOptions<
  TCollections extends Collections,
  TAlgorithms extends Algorithms
> = {
  apiConfig?: ApiConfig
  parentContext?: Context<any, TCollections, TAlgorithms>,
  resourceType?: ResourceType
  resourceName?: keyof TCollections | keyof TAlgorithms
  token?: DecodedToken
}

createContext ​

Creates a context given its options.

  • apiConfig: set by the server
  • parentContext: if you are creating the context manually from another function that already has it's context, then you may set this prop to merge the old context into the new one
  • resourceType: defaults to collection
  • resourceName: the collection/algorithm name, used to resolve it's dependencies
ts
declare const createContext: <
  TDescription extends Description,
  TCollections extends Collections,
  TAlgorithms extends Algorithms
>(options?: ContextOptions<TCollections, TAlgorithms>) => Promise<Context<TDescription, TCollections, TAlgorithms>>

Last updated: