### Example Sequence

Source: https://ga4gh.github.io/refget/sequences

A sample sequence used for demonstrating range and coordinate requests.

```text
CAACAGAGACTGCTGCTGACAGTGGGCGGGGGAGTAGTTTGCTTGGCCCGTGGTTGAGGA
```

--------------------------------

### Service Information Request and Response

Source: https://ga4gh.github.io/refget/sequences

Example of a GET request to the service-info endpoint and the corresponding JSON response body.

```json
GET /service-info

{
  "id": "org.ga4gh.refget",
  "name": "Refget server",
  "type": {
    "group": "org.ga4gh",
    "artifact": "refget-sequence",
    "version": "2.0.0"
  },
  "description": "Reference sequences from checksums",
  "organization": {
    "name": "My organization",
    "url": "https://example.com"
  },
  "contactUrl": "mailto:support@example.com",
  "documentationUrl": "https://docs.myservice.example.com",
  "createdAt": "2019-06-04T12:58:19Z",
  "updatedAt": "2019-06-04T12:58:19Z",
  "environment": "prod",
  "version": "2.0.0",
  "refget": {
    "circular_supported": true,
    "subsequence_limit": 0,
    "algorithms": [
      "md5",
      "ga4gh",
      "trunc512"
    ],
    "identifier_types": [
      "insdc",
      "refseq",
      "ensembl"
    ]
  }
}
```

--------------------------------

### Attribute endpoint response examples

Source: https://ga4gh.github.io/refget/seqcols

Examples of JSON array responses for specific attribute queries.

```json
[1216, 970, 1788]
```

```json
["A", "B", "C"]
```

--------------------------------

### Query zero-length sequence

Source: https://ga4gh.github.io/refget/sequences

Example request for a zero-length string when start and end parameters are equal.

```http
GET /sequence/6aef897c3d6ff0c78aff06ac189178dd?start=0&end=0
```

--------------------------------

### Example length array at level 2

Source: https://ga4gh.github.io/refget/decision_record

Input array of lengths before serialization.

```json
[248956422, 242193529, 198295559]
```

--------------------------------

### Service-info Response Example

Source: https://ga4gh.github.io/refget/seqcols

A sample JSON response for the /service-info endpoint, including the required seqcol schema definition.

```json
{
  "id": "org.ga4gh.refget.seqcol",
  "name": "Sequence Collection server",
  "type": {
    "group": "org.ga4gh",
    "artifact": "refget-seqcol",
    "version": "1.0.0"
  },
  "description": "Collection of sequences from digests.",
  "organization": {
    "name": "My organization",
    "url": "https://example.com"
  },
  "contactUrl": "mailto:support@example.com",
  "documentationUrl": "https://docs.myservice.example.com",
  "createdAt": "2024-01-01T11:00:00Z",
  "updatedAt": "2024-01-01T11:00:00Z",
  "environment": "prod",
  "version": "1.4.1",
  "seqcol": {
    "schema": {
      "description": "A collection of biological sequences.",
      "type": "object",
      "$id": "https://ga4gh.github.io/refget/schemas/seqcol_extended_v1.0.0.json",
      "properties": {
        "lengths": {
          "$ref": "/lengths"
        },
        "names": {
          "$ref": "/names"
        },
        "sequences": {
          "$ref": "/sequences"
        }
      },
      "required": [ 
        "names", 
        "sequences" 
      ],
      "ga4gh": {
        "inherent": [
          "names",
          "sequences"
        ]
      }
    }
  }
}
```

--------------------------------

### GET /sequence/service-info

Source: https://ga4gh.github.io/refget/sequences/pub/refget-openapi.yaml

Retrieve a summary of features and configurations supported by the API deployment.

```APIDOC
## GET /sequence/service-info

### Description
Retrieve a summary of features this API deployment supports.

### Method
GET

### Endpoint
/sequence/service-info

### Response
#### Success Response (200)
- **RefgetServiceInfo** (object) - Display of all known configurations for a service deployment
```

--------------------------------

### Metadata Request and Response Example

Source: https://ga4gh.github.io/refget/sequences

A sample request to the metadata endpoint and the corresponding JSON response structure.

```json
GET /sequence/6aef897c3d6ff0c78aff06ac189178dd/metadata

{
  "metadata" : {
    "md5" : "6aef897c3d6ff0c78aff06ac189178dd",
    "ga4gh": "SQ.Ya6Rs7DHhDeg7YaOSg1EoNi3U_nQ9SvO",
    "length": 248956422,
    "aliases" : [
      {
        "alias": "CM000663.2",
        "naming_authority" : "insdc"
      },
      {
        "alias": "chr1",
        "naming_authority" : "ucsc"
      }
    ]
  }
}
```

--------------------------------

### Retrieve sequence by identifier

Source: https://ga4gh.github.io/refget/sequences

Example request and truncated response for a sequence retrieval.

```http
GET /sequence/6aef897c3d6ff0c78aff06ac189178dd
NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN ....
```

--------------------------------

### URL Parameter for 10bp

Source: https://ga4gh.github.io/refget/sequences

Equivalent request using 0-based, half-open start and end parameters.

```text
?start=5&end=15
```

--------------------------------

### FASTA Formatted Response

Source: https://ga4gh.github.io/refget/sequences

Example of a FASTA formatted response for a range request.

```fasta
>9f5b68f3ebc5f7b06a9b2e2b55297403 5-14
GAGACTGCTG
```

--------------------------------

### UTF-8 character array

Source: https://ga4gh.github.io/refget/decision_record

Example of an array containing UTF-8 characters.

```json
["染色体-1","染色体-2","染色体-3"]
```

--------------------------------

### List endpoint response format

Source: https://ga4gh.github.io/refget/seqcols

Example JSON structure returned by the /list endpoint, demonstrating the pagination and results fields.

```json
{
  "results": [
    ...
  ],
  "pagination": {
    "page": 1,
    "page_size": 100,
    "total": 165,
  }
}
```

--------------------------------

### GET /sequence/<id>

Source: https://ga4gh.github.io/refget/sequences

Retrieves the specified sequence or sub-sequence by its unique identifier.

```APIDOC
## GET /sequence/<id>

### Description
The primary method for accessing specified sequence data. The response is the requested sequence or sub-sequence in text unless an alternative formatting supported by the server is requested.

### Method
GET

### Endpoint
/sequence/<id>

### Parameters
#### Path Parameters
- **id** (string) - Required - A string specifying an identifier uniquely associated with a sequence so that at most one sequence is returned for an id. The id can be a checksum or other unique namespaced identifier supported by the server.

### Response
#### Success Response (200)
- **body** (text/vnd.ga4gh.refget.v2.0.0+plain) - The requested sequence or sub-sequence.
```

--------------------------------

### GET /sequence/{id}

Source: https://ga4gh.github.io/refget/sequences

Retrieves a sequence or sub-sequence based on the provided identifier.

```APIDOC
## GET /sequence/{id}

### Description
Retrieves the sequence associated with the given identifier. Supports optional range specification via query parameters or the Range header.

### Method
GET

### Endpoint
/sequence/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the sequence.

#### Query Parameters
- **start** (32-bit unsigned integer) - Optional - The start position of the range (0-based, inclusive).
- **end** (32-bit unsigned integer) - Optional - The end position of the range (0-based, exclusive).

#### Request Headers
- **Range** (string) - Optional - RFC 7233 byte range for the sequence.
- **Accept** (string) - Optional - The formatting of the returned sequence (defaults to text/vnd.ga4gh.refget.v2.0.0+plain).

### Response
#### Success Response (200/206)
- **Body** (string) - The requested sequence or sub-sequence in uppercase ASCII text.

#### Error Handling
- **400 Bad Request** - Returned if parameters are invalid or conflicting.
- **404 Not Found** - Returned if the identifier is unknown.
- **406 Not Acceptable** - Returned if the requested format is not supported.
- **416 Range Not Satisfiable** - Returned if the requested range is invalid.
```

--------------------------------

### Example object structure for name-length pairs

Source: https://ga4gh.github.io/refget/decision_record

The structure used for individual name-length pairs before digestion.

```json
{"length":123,"name":"chr1"}
```

--------------------------------

### GET /service-info

Source: https://ga4gh.github.io/refget/seqcols

Retrieves information about the service, including the Seqcol JSON schema used by the server.

```APIDOC
## GET /service-info

### Description
The service info endpoint provides information about the service, including a `seqcol` property containing the JSON schema implemented by the server.

### Method
GET

### Endpoint
/service-info

### Response
#### Success Response (200)
- **id** (string) - The service ID
- **name** (string) - The service name
- **type** (object) - Service type information
- **seqcol** (object) - Contains the `schema` attribute defining the collection structure

#### Response Example
{
  "id": "org.ga4gh.refget.seqcol",
  "name": "Sequence Collection server",
  "seqcol": {
    "schema": {
      "description": "A collection of biological sequences.",
      "type": "object"
    }
  }
}
```

--------------------------------

### Example /comparison return value

Source: https://ga4gh.github.io/refget/seqcols

A JSON object representing the required structure for the /comparison endpoint response, including digests, attributes, and array element counts.

```json
{
  "digests": {
    "a": "514c871928a74885ce981faa61ccbb1a",
    "b": "c345e091cce0b1df78bfc124b03fba1c"
  },
  "attributes": {
    "a_only": [],
    "b_only": [],
    "a_and_b": [
      "lengths",
      "names",
      "sequences"
    ]
  },
  "array_elements": {
    "a_count": {
      "lengths": 195,
      "names": 195,
      "sequences": 195
    },
    "b_count": {
      "lengths": 25,
      "names": 25,
      "sequences": 25
    },
    "a_and_b_count": {
      "lengths": 25,
      "names": 25,
      "sequences": 0
    },
    "a_and_b_same_order": {
      "lengths": false,
      "names": false,
      "sequences": null
    }
  }
}
```

--------------------------------

### GET /sequence/{id}/metadata

Source: https://ga4gh.github.io/refget/sequences/pub/refget-openapi.yaml

Retrieve metadata about a reference sequence using its hash identifier.

```APIDOC
## GET /sequence/{id}/metadata

### Description
Retrieve a metadata about a reference sequence using a hash identifier.

### Method
GET

### Endpoint
/sequence/{id}/metadata

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier to use. Should be a checksum hash.

### Response
#### Success Response (200)
- **Metadata** (object) - Successful retrieval of sequence metadata.
```

--------------------------------

### POST body for local comparison

Source: https://ga4gh.github.io/refget/decision_record

Example of a level 2 sequence collection JSON structure used for the POST /comparison/{digest1} endpoint.

```json
{
  "lengths": [
    "248956422",
    "242193529",
    "198295559"
  ],
  "names": [
    "chr1",
    "chr2",
    "chr3"
  ],
  "sequences": [
    "a004bc1b0bf05fc668cab6bbfd93d3eb",
    "0ccf3a67666ac53f99fcad19768f2dde",
    "bda7b228789169ae811dd8d676d517ca"
  ]
}
```

--------------------------------

### GET /sequence/<id>/metadata

Source: https://ga4gh.github.io/refget/sequences

Retrieves all known names and metadata for a specific sequence identifier.

```APIDOC
## GET /sequence/<id>/metadata

### Description
Returns all known names for an identifier and related metadata. This allows clients to query all known names for a given identifier as well as fetch any associated metadata.

### Method
GET

### Endpoint
/sequence/<id>/metadata

### Parameters
#### Path Parameters
- **id** (string) - Required - A string specifying an identifier to retrieve metadata for using one of the defined checksum algorithms or a server-specific checksum algorithm.

#### Request Parameters
- **Accept** (string) - Optional - The formatting of the returned metadata, defaults to application/vnd.ga4gh.refget.v2.0.0+json.

### Response
#### Success Response (200)
- **metadata** (object) - Container for response object.
- **metadata.md5** (string) - md5 checksum.
- **metadata.ga4gh** (string) - ga4gh identifier, or null if not supported.
- **metadata.length** (int) - The length of the reference sequence.
- **metadata.aliases** (array of objects) - Array of objects each containing one of the known aliases.
- **metadata.aliases.alias** (string) - A known alias for the query.
- **metadata.aliases.naming_authority** (string) - The source of the alias.

### Response Example
{
  "metadata" : {
    "md5" : "6aef897c3d6ff0c78aff06ac189178dd",
    "ga4gh": "SQ.Ya6Rs7DHhDeg7YaOSg1EoNi3U_nQ9SvO",
    "length": 248956422,
    "aliases" : [
      {
        "alias": "CM000663.2",
        "naming_authority" : "insdc"
      },
      {
        "alias": "chr1",
        "naming_authority" : "ucsc"
      }
    ]
  }
}
```

--------------------------------

### Define a JSON Schema for Seqcol

Source: https://ga4gh.github.io/refget/seqcols

Example of a JSON schema using a reference to the base seqcol schema for sequence collection validation.

```yaml
description: "A collection of biological sequences."
type: object
"$id": "https://ga4gh.github.io/refget/schemas/seqcol_extended_v1.0.0.json",  # URI to seqcol schema with ancillary attributes
properties:
  lengths:
    "$ref": "/lengths"
  names:
    "$ref": "/names"
  sequences:
    "$ref": "/sequences"
required:
  - lengths
  - names
  - sequences
ga4gh:
  inherent:
    - names
    - sequences
```

--------------------------------

### URL Parameter for Single Base Pair

Source: https://ga4gh.github.io/refget/sequences

Equivalent request for a single base pair using start and end parameters.

```text
?start=0&end=1
```

--------------------------------

### Define a local property qualifier

Source: https://ga4gh.github.io/refget/seqcols

Example of specifying a property type using a local qualifier within a JSON schema properties block.

```yaml
properties:
  names:
    type: array
```

--------------------------------

### GET /comparison/:digest1/:digest2

Source: https://ga4gh.github.io/refget/seqcols

Compares two sequence collections identified by their respective digests.

```APIDOC
## GET /comparison/:digest1/:digest2

### Description
Compares two sequence collections using their level 0 seqcol digests.

### Method
GET

### Endpoint
/comparison/:digest1/:digest2

### Parameters
#### Path Parameters
- **digest1** (string) - Required - The digest of the first sequence collection.
- **digest2** (string) - Required - The digest of the second sequence collection.

### Response
#### Success Response (200)
- **digests** (object) - Contains keys 'a' and 'b' with the level 0 seqcol digests.
- **attributes** (object) - Contains 'a_only', 'b_only', and 'a_and_b' lists of array names.
- **array_elements** (object) - Contains 'a_count', 'b_count', 'a_and_b_count', and 'a_and_b_same_order' metrics.
```

--------------------------------

### Define an object-level required qualifier

Source: https://ga4gh.github.io/refget/seqcols

Example of specifying a required property using an object-level list parallel to the properties keyword.

```yaml
properties:
  names:
    type: array
required:
  - names
```

--------------------------------

### Canonical Seqcol Object Representation

Source: https://ga4gh.github.io/refget/seqcols

An example of a sequence collection structured as a canonical seqcol object with matching array lengths.

```json
{
  "lengths": [
    248956422,
    242193529,
    198295559
  ],
  "names": [
    "chr1",
    "chr2",
    "chr3"
  ],
  "sequences": [
    "SQ.2YnepKM7OkBoOrKmvHbGqguVfF9amCST",
    "SQ.lwDyBi432Py-7xnAISyQlnlhWDEaBPv2",
    "SQ.Eqk6_SvMMDCc6C-uEfickOUWTatLMDQZ"
  ]
}
```

--------------------------------

### GET /list/:object_type

Source: https://ga4gh.github.io/refget/seqcols

Lists identifiers for a given object type, such as collections. Supports pagination and filtering by attribute values.

```APIDOC
## GET /list/:object_type

### Description
Lists identifiers for a given object type in singular form. This endpoint provides a way to discover what sequence collections a service provides and supports filtering by attribute values.

### Method
GET

### Endpoint
/list/:object_type

### Parameters
#### Path Parameters
- **object_type** (string) - Required - The singular descriptor of the object type (e.g., 'collection').

#### Query Parameters
- **page** (integer) - Optional - Page number, starting at 0.
- **page_size** (integer) - Optional - Number of items per page.
- **:attribute** (string) - Optional - Filter results by a specific level 1 attribute digest.

### Response
#### Success Response (200)
- **results** (array) - A paged list of identifiers.
- **pagination** (object) - Pagination metadata including page, page_size, and total count.
```

--------------------------------

### GET /collection/:digest

Source: https://ga4gh.github.io/refget/seqcols

Retrieves a sequence collection from the database keyed by the unique top-level digest.

```APIDOC
## GET /collection/:digest

### Description
Retrieves the original sequence collection from a database, keyed by the unique top-level digest. The structure of the returned data is modulated by the `level` query parameter.

### Method
GET

### Endpoint
/collection/:digest

### Parameters
#### Path Parameters
- **digest** (string) - Required - The unique seqcol digest

#### Query Parameters
- **level** (integer) - Optional - The expansion level of the returned sequence collection (default: 2). Level 2 returns the canonical structure, level 1 returns the collection with digested attributes.
```

--------------------------------

### GET /sequence/{id}

Source: https://ga4gh.github.io/refget/sequences/pub/refget-openapi.yaml

Retrieve a reference sequence using a hash function, with optional support for subsequence retrieval via query parameters or HTTP Range headers.

```APIDOC
## GET /sequence/{id}

### Description
Retrieve a reference sequence using a hash function.

### Method
GET

### Endpoint
/sequence/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier to use. Should be a checksum hash identifier.

#### Query Parameters
- **start** (integer) - Optional - Request a subsequence of the data (0-based).
- **end** (integer) - Optional - Request a subsequence of the data by specifying the end.

### Response
#### Success Response (200)
- **sequence** (string) - Successful retrieval of sequence. Returned as a single string with no line breaks.
```

--------------------------------

### Import Required Libraries

Source: https://ga4gh.github.io/refget/sequences/pub/ga4gh_and_TRUNC512_identifiers.pl

Imports the necessary modules for base64 encoding, hashing, and binary conversion.

```python
# Importing the 3 libraries we need
import base64
import hashlib
import binascii
```

--------------------------------

### Execute Identifier Generation and Conversion

Source: https://ga4gh.github.io/refget/sequences/pub/ga4gh_and_TRUNC512_identifiers.pl

Demonstrates usage of the defined functions to generate identifiers and perform conversions.

```python
print("GA4GH identifier: {}".format(ga4gh_digest('ACGT')))
print("GA4GH identifier +3 bits: {}".format(ga4gh_digest('ACGT', 27)))
print("")

print("A deprecated/legacy TRUNC512 {} can be translated to GA4GH {}".format(trunc512_digest('ACGT'), trunc512_to_ga4gh(trunc512_digest('ACGT'))))
print("")
print("Empty GA4GH identifier: {}".format(ga4gh_digest("")))
```

--------------------------------

### Compute seqcol encoding in Python

Source: https://ga4gh.github.io/refget/seqcols/digest_from_collection

Demonstrates the manual implementation of the seqcol digest algorithm, including canonicalization and GA4GH digest functions.

```python
# Demo for encoding a sequence collection

import base64
import hashlib
import json

def canonical_str(item: dict) -> bytes:
    """Convert a dict into a canonical string representation"""
    return json.dumps(
        item, separators=(",", ":"), ensure_ascii=False, allow_nan=False, sort_keys=True
    ).encode("utf8")

def sha512t24u_digest(seq: bytes) -> str:
    """ GA4GH digest function """
    offset = 24
    digest = hashlib.sha512(seq).digest()
    tdigest_b64us = base64.urlsafe_b64encode(digest[:offset])
    return tdigest_b64us.decode("ascii")

# 1. Get data as canonical seqcol object representation

seqcol_obj = {
  "lengths": [
    248956422,
    133797422,
    135086622
  ],
  "names": [
    "chr1",
    "chr2",
    "chr3"
  ],
  "sequences": [
    "SQ.2648ae1bacce4ec4b6cf337dcae37816",
    "SQ.907112d17fcb73bcab1ed1c72b97ce68",
    "SQ.1511375dc2dd1b633af8cf439ae90cec"
  ]
}

# Step 1a: Remove any non-inherent attributes,
# so that only the inherent attributes contribute to the digest.
# Only names and sequences are inherent.

seqcol_obj_inherent = {
  "names": seqcol_obj["names"],
  "sequences": seqcol_obj["sequences"]
}

# Step 2: Apply RFC-8785 to canonicalize the value 
# associated with each attribute individually.

seqcol_obj2 = {}
for attribute in seqcol_obj_inherent:
    seqcol_obj2[attribute] = canonical_str(seqcol_obj_inherent[attribute])
seqcol_obj2  # visualize the result

# Step 3: Digest each canonicalized attribute value
# using the GA4GH digest algorithm.

seqcol_obj3 = {}
for attribute in seqcol_obj2:
    seqcol_obj3[attribute] = sha512t24u_digest(seqcol_obj2[attribute])
print(json.dumps(seqcol_obj3, indent=2))  # visualize the result

# Step 4: Apply RFC-8785 again to canonicalize the JSON 
# of new seqcol object representation.

seqcol_obj4 = canonical_str(seqcol_obj3)
seqcol_obj4  # visualize the result

# Step 5: Digest the final canonical representation again.

seqcol_digest = sha512t24u_digest(seqcol_obj4)
# Answer: 'KxZO6qIbVNCIKtQj0WR3fwzg2rsJLlC3'

# Equivalent to:
# import refget
# sc = refget.SequenceCollection.from_dict(seqcol_obj)
# sc.digest
```

--------------------------------

### Default Content-Type Header

Source: https://ga4gh.github.io/refget/sequences

The default media type for the metadata response.

```http
Content-type: application/vnd.ga4gh.refget.v2.0.0+json
```

--------------------------------

### Range Header for 10bp

Source: https://ga4gh.github.io/refget/sequences

Requesting 10 base pairs using an inclusive byte range.

```http
Range: bytes=5-14
```

--------------------------------

### Specify Protocol Version in Accept Header

Source: https://ga4gh.github.io/refget/sequences

Use the Accept header to specify the protocol version when making requests to the server.

```http
Accept: text/vnd.ga4gh.refget.v2.0.0+plain
```

--------------------------------

### GET /attribute/:object_type/:attribute_name/:digest

Source: https://ga4gh.github.io/refget/seqcols

Retrieves the value of a specific attribute for a sequence collection based on its level 1 digest.

```APIDOC
## GET /attribute/:object_type/:attribute_name/:digest

### Description
Retrieves values of specific attributes in a sequence collection. The result structure corresponds to the value of the attribute in the canonical structure.

### Method
GET

### Endpoint
/attribute/:object_type/:attribute_name/:digest

### Parameters
#### Path Parameters
- **object_type** (string) - Required - The object type (e.g., 'collection').
- **attribute_name** (string) - Required - The name of the attribute (e.g., 'sequences', 'names').
- **digest** (string) - Required - The level 1 digest of the attribute value.

### Response
#### Success Response (200)
- **value** (any) - The attribute value identified by the digest.
```

--------------------------------

### Returned Sub-sequence

Source: https://ga4gh.github.io/refget/sequences

The resulting sub-sequence from the specified range request.

```text
GAGACTGCTG
```

--------------------------------

### POST /comparison/:digest1

Source: https://ga4gh.github.io/refget/seqcols

Compares a server-side sequence collection (by digest) with a user-provided local collection.

```APIDOC
## POST /comparison/:digest1

### Description
Compares a server-side sequence collection (identified by digest) with a local collection provided in the request body.

### Method
POST

### Endpoint
/comparison/:digest1

### Parameters
#### Path Parameters
- **digest1** (string) - Required - The digest of the server-side sequence collection.

#### Request Body
- **body** (object) - Required - The local sequence collection provided as a level 2 canonical seqcol representation.

### Response
#### Success Response (200)
- **digests** (object) - Contains keys 'a' and 'b' with the level 0 seqcol digests.
- **attributes** (object) - Contains 'a_only', 'b_only', and 'a_and_b' lists of array names.
- **array_elements** (object) - Contains 'a_count', 'b_count', 'a_and_b_count', and 'a_and_b_same_order' metrics.
```

--------------------------------

### Define collated attributes with local qualifiers

Source: https://ga4gh.github.io/refget/decision_record

Example of marking attributes as collated or not using local qualifiers within a JSON schema object definition.

```yaml
description: "A collection of biological sequences."
type: object
properties:
  lengths:
    type: array
    collated: true
    description: "Number of elements, such as nucleotides or amino acids, in each sequence."
    items:
      type: integer
  author:
    type: string
    collated: false
    description: "The author of this sequence collection"
...
```

--------------------------------

### Default Content-Type header

Source: https://ga4gh.github.io/refget/sequences

The standard encoding header for sequence retrieval responses.

```http
Content-type: text/vnd.ga4gh.refget.v2.0.0+plain
```

--------------------------------

### Default Content-Type Header

Source: https://ga4gh.github.io/refget/sequences

The default Content-Type header for the service-info endpoint.

```http
Content-type: application/vnd.ga4gh.refget.v2.0.0+json

```

--------------------------------

### Specify Content-Type for JSON Responses

Source: https://ga4gh.github.io/refget/sequences

Include the protocol version and encoding in the Content-Type header for JSON responses.

```http
Content-Type: application/vnd.ga4gh.refget.v2.0.0+json; charset=us-ascii
```

--------------------------------

### Represent sequence collection as a dictionary of digests

Source: https://ga4gh.github.io/refget/decision_record

Shows the multi-tiered digest approach where each array component is represented by its own digest.

```python
{ 'sequences': '8dd93796fa0225e92eb159a8779f1b254776557f748f8bfb',
 'lengths': '501fd98e2fdcc276c47306bd72c9155489ed2b23123ddfa2',
 'names': '7bc90a07cf25f2f64f33baee3d420ad1ae5f442055280d43',
}
```

--------------------------------

### Level 0 digest

Source: https://ga4gh.github.io/refget/seqcols

The top-level digest representing 0 database lookups.

```text
Zjx9_tD2o-1yKB6RR2v2g3W9c5ufydUc
```

--------------------------------

### Serialized length array

Source: https://ga4gh.github.io/refget/decision_record

The output of the Python implementation after applying RFC-8785.

```python
b'[248956422,242193529,198295559]'
```

--------------------------------

### Range Header for Single Base Pair

Source: https://ga4gh.github.io/refget/sequences

Requesting a single base pair using an inclusive byte range.

```http
Range: bytes=0-0
```

--------------------------------

### Compute GA4GH digest in Python

Source: https://ga4gh.github.io/refget/seqcols

Implements the sha512t24u algorithm by performing a SHA-512 digest, truncating to 24 bytes, and encoding with base64url.

```python
import base64
import hashlib

def sha512t24u_digest(seq: bytes) -> str:
    """ GA4GH digest function """
    offset = 24
    digest = hashlib.sha512(seq).digest()
    tdigest_b64us = base64.urlsafe_b64encode(digest[:offset])
    return tdigest_b64us.decode("ascii")
```

--------------------------------

### seqcol minimal v1.0.0 JSON Schema

Source: https://ga4gh.github.io/refget/schemas/seqcol_minimal_v1.0.0.json

The formal JSON schema defining the required properties and structure for a seqcol minimal object.

```json
{
  "description": "A collection of biological sequences.",
  "type": "object",
  "properties": {
    "lengths": {
      "type": "array",
      "collated": true,
      "description": "Number of elements, such as nucleotides or amino acids, in each sequence.",
      "items": {
        "type": "integer"
      }
    },
    "names": {
      "type": "array",
      "collated": true,
      "description": "Human-readable labels of each sequence (chromosome names).",
      "items": {
        "type": "string"
      }
    },
    "sequences": {
      "type": "array",
      "collated": true,
      "items": {
        "type": "string",
        "description": "Refget sequences v2 identifiers for sequences."
      }
    }
  },
  "required": [
    "names",
    "lengths",
    "sequences"
  ],
  "ga4gh": {
    "inherent": [
      "names",
      "sequences"
    ]
  }
}
```

--------------------------------

### Canonical object representation

Source: https://ga4gh.github.io/refget/decision_record

The canonical representation of the sequence collection object using RFC-8785.

```python
b'{"lengths":"5K4odB173rjao1Cnbk5BnvLt9V7aPAa2","names":"g04lKdxiYtG3dOGeUC5AdKEifw65G0Wp","sequences":"EiYgJtUfGyad7wf5atL5OG4Fkzohp2qe"}'
```

--------------------------------

### Define Sequence Collection Schema in YAML

Source: https://ga4gh.github.io/refget/decision_record

Illustrative YAML representation of the JSON Schema used to define the structure and properties of a sequence collection.

```yaml
description: "A collection of sequences, representing biological sequences including nucleotide or amino acid sequences. For example, a sequence collection may represent the set of chromosomes in a reference genome, the set of transcripts in a transcriptome, a collection of reference microbial sequences of a specific gene, or any other set of sequences."
type: object
properties:
  lengths:
    type: array
    description: "Number of elements, such as nucleotides or amino acids, in each sequence."
    items:
      type: integer
  masks:
    type: array
    description: "Digests of subsequence masks indicating subsequences to be excluded from an analysis, such as repeats"
    items:
      type: string
  names:
    type: array
    description: "Human-readable identifiers of each sequence, commonly called chromosome names."
    items:
      type: string
  priorities:
    type: array
    description: "Annotation of whether each sequence is a primary or secondary component in the collection."
    items:
      type: boolean
  sequences:
    type: array
    description: "Digests of sequences computed using the GA4GH digest algorithm (sha512t24u)."
    items:
      type: string
      description: "Actual sequence content"
  topologies:
    type: array
    description: "Annotation of whether each sequence represents a linear or other topology."
    items:
      type: string
      enum: ["circular", "linear"]
      default: "linear"
required:
  - lengths
digested:
  - lengths
  - names
  - masks
  - priorities
  - sequences
  - topologies
```