RCSB PDB: 1D Coordinate Server API Documentation

  • 1D Coordinate Server API Basics
  • Data Organization
  • Examples
  • License
  • Acknowledgements
  • Contact Us

    • RCSB PDB 1D Coordinate Server API

    The RCSB PDB 1D Coordinate Server compiles alignments between structural and sequence databases and integrates protein positional features from multiple resources. Alignment data is available for NCBI RefSeq (including protein and genomic sequences), UniProt and PDB sequences. Protein positional features are integrated from UniProt, CATH, SCOPe and RCSB PDB and collected from the RCSB PDB Data Warehouse. The server offers a GraphQL-based application programming interface (API) to access the integrated content.

    GraphQL-based API

    GraphQL server operates on a single URL/endpoint, https://1d-coordinates.rcsb.org/graphql, and all GraphQL requests for this service should be directed at this endpoint. GraphQL HTTP server handles the HTTP GET and POST methods.

    GET request

    If the "query" is passed in the URL as a query parameter, the request will be parsed and handled as the HTTP GET request. For example, to execute the following GraphQL query:

    This query string should be sent via an HTTP like so:

    In the example above, the query arguments are written inside the query string. The query arguments can also be passed as dynamic values that are called variables. The variable definition looks like ($id: String!) in the example below. It lists a variable, prefixed by $, followed by its type, in this case String (! indicates that a non-null argument is required).

    The following is equivalent to the previous query:

    Where:

    With variable defined like so:

    Query variables, in this case, should be sent as a URL-encoded string in an additional query parameter called variables.

    POST request

    The GraphQL server accepts POST requests with a JSON-encoded body. A valid GraphQL POST request should use the application/json content type, must include query, and may include variables. Here's an example for a valid body of a POST request:

    Response

    Regardless of the method by which the query and variables were sent, the response is returned in JSON format. A query might result in some data and some errors. The successful response will be returned in the form of:

    Error Handling

    Error handling in REST is pretty straightforward, we simply check the HTTP headers to get the status of a response. Depending on the HTTP status code we get ( 200 or 404), we can easily tell what the error is and how to go about resolving it. GraphQL server, on the other hand, will always respond with a 200 OK status code. When an error occurs while processing GraphQL queries, the complete error message is sent to the client with the response. Below is a sample of a typical GraphQL error message when requesting a field that is not defined in the GraphQL schema:

    Using GraphQL

    GraphQL enables declarative data fetching and gives power to request exactly the data that is needed. The GraphQL end point defines two different queries for sequence alignments and positional features:

    Alignment Query

    alignment(from: SequenceReference!, to: SequenceReference!, queryId: String!, range:[Int!])

    Next table describes the type of database identifiers used for each SequenceReference value

    SequenceReference Database Identifier Example
    NCBI_GENOME NCBI RefSeq Chromosome Accession NC_000001
    NCBI_PROTEIN NCBI RefSeq Protein Accession NP_789765
    UNIPROT UniProt Accession P01112
    PDB_ENTITY RCSB PDB Entity Id / CSM Entity Id 2UZI_3 / AF_AFP68871F1_1
    PDB_INSTANCE RCSB PDB Instance Id / CSM Instance Id 2UZI.C / AF_AFP68871F1.A

    Annotations Query

    annotations(reference: SequenceReference!, queryId: String!, sources: [Source!]!, range:[Int!], filters:[FilterInput!])

    Data Organization

    Schemas used to encode sequence alignments and positional features are extensions of the data schemas used in the RCSB PDB Data API. The following definitions and structures are relevant to the way that alignments and annotations are encoded:

    Alignments
    GraphiQL
    Protein-Protein Alignment diagram of a sequence alignment between a NCBI protein and PDB Entity. Residues are mapped one by one from starting to end positions within two different regions.
    GraphiQL
    Genome-Protein Alignment diagram of a sequence alignment between a NCBI genome region and a PDB Entity. Protein residues are mapped to 3 consecutive genome indexes from the starting to the end position. In those cases where the last nucleotide triad indexes would surpass the ending position then, the missing nucleotides are stored in exon_shift. In this example this situation occurs in the first AlignedRegion where PDB Entity residue index 7 is mapped to genome nucleotide indexes [8,13,14].
    Annotations

    Data Schema

    JSON schemas for alignment and annotations services are built through references to the RCSB PDB Data API schemas and extended following the same conventions.

    GraphQL Schema

    All GraphQL queries are validated and executed against the GraphQL schema. The GraphQL schema contains the elements that define sequence alignments and positional features.

    You can use GraphiQL, which is a "graphical interactive in-browser GraphQL IDE", to explore GraphQL schema. It lets you try different queries, helps with auto completion and built-in validation. The collapsible Docs panel (Documentation Explorer) on the right side of the page allows you to navigate through the schema definitions. Click on the root Query link to start exploring the GraphQL schema.

    GraphiQL

    Examples

    This section contains additional examples for using the GraphQL-based RCSB PDB 1D Coordinate Server API.

    UniProt - PDB Entity alignment

    Fetch alignments between a UniProt Accession and PDB Entities:

    Computed Structure Model - NCBI protein alignment

    Fetch alignments between a Computed Structure Model and NCBI proteins:

    Mapping UniProt annotations to a PDB Instance

    Fetch all positional features for a particular PDB Instance:

    Human Chromosome 1 - PDB Entity alignment

    Map all PDB Entities that fall in Human Chromosome 1:

    Mapping PDB Instance ligands binding sites to Human Chromosome 1

    Fetch protein-ligand binding sites for PDB Instances that fall within Human Chromosome 1:

    Note, that label_asym_id is used to identify polymer entity instances.

    Mapping a PDB Instance to NCBI RefSeq proteins

    Fetch alignments between a PDB Instance and NCB RefSeq proteins:

    License

    1D Coordinate Server usage is available under the same terms and condition as RCSB PDB (see usage policies)

    Acknowledgements

    To cite this service, please reference:

    Contact Us

    Contact info@rcsb.org with questions or feedback about this service.