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.

Every write is attributed to the user the token names, in the first of its username, name, login and email claims: that is the account the version history and the audit columns show. A token that names no user is attributed to System.

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",
  "aliases": ["Et2Gly"],
  "isomerLabel": null,
  "resolvedFrom": null,
  "resolvedFromId": null,
  "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. aliases is always present on output, [] when there are none, and lists your organisation's aliases and the public ones; on input it is ignored unless the PUT carries aliases=replace. capGroupSMILES may be omitted: it is derived from the cap group name. See Monomer Fields.

Three fields carry enhanced stereochemistry; see Enhanced Stereochemistry:

A smiles is returned as CXSMILES when the structure carries a stereo group, for example C[C@@H](N[*:1])C([*:2])=O |&1:1|; a molfile as V3000.

Molfiles and the chiral flag

Accepted on PUT /monomer/{polymertype}/{symbol}, POST /monomer/import and POST /structure/sdf/smiles. See Enhanced Stereochemistry.

A structure stating stereochemistry the library cannot store is refused, with 409 on PUT and a validation: error on an import row, rather than stored as something else:

Validation messages returned with 409:

A successful PUT carries an X-Monomer-Outcome header: CREATED, UPDATED, or ALIASED when nothing was registered because the symbol became an alias. It may also carry one or more X-Monomer-Warning headers, percent-encoded. The write stands in every case:

• a resolved monomer settled an or group the same way as the child of a labelled sibling, where mirror images were expected; the same text is in warnings[] of the stereo analysis;
• a stereo group said nothing about the structure, which is a meso form: The stereo group &1 (atoms 3, 8) says nothing about this structure: inverting its centres gives the same molecule (a meso form), so its centres are registered as absolute. The monomer is keyed as drawn, so the same compound sent again with or without the group is a duplicate.

Stereoisomers of a monomer

GET /monomer/PEPTIDE/Phx3/stereoisomers, for Phx3 registered as the L form resolved from the unknown Phx1 (label A), with Phx4 its D form resolved from Phx2 (label B) and a racemate racPhx:

{
  "monomer": "Phx3",
  "id": 1203,
  "isomerLabel": null,
  "statement": "abs",
  "resolvedFrom": "Phx1",
  "stereoisomers": [
    {
      "relation": "enantiomer",
      "link": null,
      "id": 1204,
      "symbol": "Phx4",
      "name": "D-phenylalanine analogue",
      "isomerLabel": null,
      "statement": "abs",
      "smiles": "O=C([*:2])[C@H](Cc1ccccc1)N[*:1]",
      "status": "live"
    },
    {
      "relation": "unknownForm",
      "link": "resolvedFrom",
      "id": 1201,
      "symbol": "Phx1",
      "name": "Phenylalanine analogue, flask A",
      "isomerLabel": "A",
      "statement": "or",
      "smiles": "O=C([*:2])[C@@H](Cc1ccccc1)N[*:1] |o1:3|",
      "status": "live"
    },
    {
      "relation": "unknownForm",
      "link": null,
      "id": 1202,
      "symbol": "Phx2",
      "name": "Phenylalanine analogue, flask B",
      "isomerLabel": "B",
      "statement": "or",
      "smiles": "O=C([*:2])[C@@H](Cc1ccccc1)N[*:1] |o1:3|",
      "status": "retired"
    },
    {
      "relation": "racemate",
      "link": null,
      "id": 1200,
      "symbol": "racPhx",
      "name": "Phenylalanine analogue, racemate",
      "isomerLabel": null,
      "statement": "&",
      "smiles": "O=C([*:2])[C@@H](Cc1ccccc1)N[*:1] |&1:3|",
      "status": "live"
    }
  ]
}

The same call on Phx1 lists Phx3 as resolvedForm with link: "resolvedChild", Phx4 as resolvedForm, Phx2 as labelSibling and racPhx as racemate. On racPhx, the four others are resolvedForm. Live entries come first, then retired ones; within each group the symbols are sorted. A client that suggests a substitution reads relation and keeps the entries whose status is live.

Aliases

A monomer answers to its symbol and to any number of aliases. Your aliases are visible to your organisation only, and may name your own monomers or public ones; public aliases are read-only. Within a polymer type a name, symbol or alias, points to one monomer, case-sensitively, and an alias cannot contain /. See Monomer Aliases.

{polymertype} is PEPTIDE, RNA or CHEM on these paths. An alias is stored trimmed, case kept, and at most 500 characters long.

On PUT /monomer/{polymertype}/{symbol}:

A refused alias, 409 ALIAS_CONFLICT or 400 for a / or an over-long name, leaves nothing written. GET /svg/{polymertype}/{name} also accepts an alias. DELETE /monomer/... and the versions and revive paths do not: they take a symbol or an identifier.

HELM validation and conversion in the other Biotoolkit services accept aliases and keep them as written in their output. They read the library through a cache, so a new alias can take up to five minutes to be accepted there.

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. Aliases come from an aliases column or SDF field, /-separated, or a JSON aliases array; they are added to the monomer the row lands on, never removed. 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, "aliased": 0},
  "total": 3
}

Rows keep the input order. ALREADY_EXISTS_SYMBOL and DUPLICATE_STRUCTURE are benign: the monomer is already there. ALIASED, with onStructureConflict=alias, means the row's symbol was added as an alias of the monomer that has the structure, and is counted in aliased. FAILED is the only error status; an alias refused for a row fails that row, with an alias-conflict: message naming the monomer that holds the name. Error strings start with a category, parse:, validation:, conversion:, duplicate-structure:, already-exists:, aliased:, alias-conflict:, 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.

Cap groups

The cap group vocabulary: the groups that can close an attachment point. Your organisation's vocabulary is the public cap groups plus its own, whose codes never repeat a public one.

Rules for a cap group's fields, the same as on the application's Cap groups page: code at most 50 characters, without ,, ; or :, and not manage or refresh; name at most 250 characters, without , or ;; template at most 500 characters, carrying [*:{n}] exactly once and no space; description at most 1000 characters; displayOrder an integer or null. A field that breaks a rule is a 400 naming the field.

The write endpoints address your organisation's cap groups only: a public code, and another organisation's code, are 404, and the public organisation never writes (403). They check no role. Every write reaches the other Biotoolkit services, which reload your vocabulary.

See Attachment Points and CAP Groups and How to Manage Your Organisation's Cap Groups.

Structure conversions

Two conversions that write nothing.

Images

Rules

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

Related

• Import File Format: the same fields as the columns of an import file
• Versioning and Deletion: the semantics of versions, revive, force and purge