REST API

The HTTP interface of the Biotoolkit Monomer Service. It is the interface Ideation and the other Biotoolkit services use, and it is available to your own integrations.

Base URL and Swagger UI

Ask your Discngine contact for the host of your deployment. The Swagger UI is the authoritative description of the request and response schemas for the version you are running.

Authentication

Every request carries a JWT, presented as Authorization: Bearer <token> and issued through the Discngine Admin Center. The token identifies your organisation, and every read and write is scoped to it: you see the public library and your own monomers, and nobody else's. A request without a valid token is answered with 401.

Public monomers are readable by everyone and writable by nobody: a write against one returns 403.

Error envelope

Errors carry a JSON body with an outcome and a message:

503 means the database or the chemistry service is unavailable, and carries Retry-After: 30. 501 means the operation is not supported by the storage backend of the deployment.

Monomers

{polymertype} is PEPTIDE, RNA or CHEM. Read operations also accept ALL.

Monomer object

{
  "symbol": "Deg",
  "name": "Diethylglycine",
  "polymerType": "PEPTIDE",
  "monomerType": "Backbone",
  "naturalAnalog": "X",
  "smiles": "CCC(CC)(N[*:1])C([*:2])=O",
  "author": "M. Curie",
  "rgroups": [
    {"label": "R1", "capGroupName": "H",  "capGroupSMILES": "[*:1][H]", "alternateId": "R1-H"},
    {"label": "R2", "capGroupName": "OH", "capGroupSMILES": "O[*:2]",   "alternateId": "R2-OH"}
  ]
}

symbol, name, polymerType, monomerType and a structure, smiles or molfile, are required. id, createDate and versionNo are server-owned and ignored on input. capGroupSMILES may be omitted: it is derived from the cap group name. See Monomer Fields.

Validation messages returned with 409:

Bulk import

A synchronous import returns 207 directly and is limited to 100 rows by default. Above that, or above the upload size, the service answers 413 with the instruction to use mode=async. An asynchronous import returns 202 with a Location header to poll. An organisation is limited to a few submissions per minute and a few concurrent jobs; 429 and 503 name the limit that was hit.

Flat-file conventions for this endpoint: column names are matched ignoring case, spaces, underscores and hyphens; CSV is semicolon-delimited; the rgroups cell is R1:H;R2:OH in one quoted cell; SDF data fields R1 to R10 carry the cap group names. Unlike the application's import page, name and monomer_type are required here.

Result body:

{
  "rows": [
    {"index": 0, "symbol": "Ahp", "status": "CREATED", "errors": []},
    {"index": 1, "symbol": "MeNva", "status": "ALREADY_EXISTS_SYMBOL", "errors": ["already-exists: symbol MeNva"]},
    {"index": 2, "symbol": "PEG2", "status": "FAILED", "errors": ["validation: Invalid cap group \"OME\" for R2. Valid values: H, OH, NH2, Azide, Ethynyl"]}
  ],
  "counts": {"created": 1, "updated": 0, "alreadyExists": 1, "duplicateStructure": 0, "failed": 1},
  "total": 3
}

Rows keep the input order. ALREADY_EXISTS_SYMBOL and DUPLICATE_STRUCTURE are benign: the monomer is already there. FAILED is the only error status. Error strings start with a category, parse:, validation:, conversion:, duplicate-structure:, already-exists:, timeout:, persist: or failed:, and never contain database or toolkit internals; a reference such as (ref: 1a2b3c4d5e6f) lets Discngine support find the detail. Re-submitting a batch is safe: the key is the symbol within the polymer type.

Images

Rules

HELM business rules, evaluated by the notation toolkit when a sequence is validated.

Related

• Monomer Fields
• Versioning and Deletion: the semantics of versions, revive, force and purge