# Sequences Client tutorial

## Introduction 

This tutorial will show you how to use the `refget.SequenceClient` class to interact with a remote Refget sequences API.

<div class="admonition success">
  <p class="admonition-title">Learning objectives</p>
  <ul>
    <li>How do I connect to a remote refget sequences API?</li>
    <li>How do I retrieve sequences by their digest?</li>
    <li>How do I get sequence metadata and service information?</li>
    <li>How does error handling work when sequences are not found?</li>
  </ul>
</div>

First, record some versions used in this tutorial:


```python
from platform import python_version 
python_version()
```




    '3.12.3'




```python
import refget
refget.__version__
```




    '0.10.0'



## Connecting to a remote API

The refget package provides a simple Python wrapper around a remote hosted refget sequences API. Provide the base url when construction a `SequenceClient` object and you can retrieve sequences from the remote server.


```python
from refget.clients import SequenceClient

seq_client = SequenceClient(urls=["https://beta.ensembl.org/data/refget/"])
```


```python
seq_client.get_sequence("6681ac2f62509cfc220d78751b8dc524", start=0, end=10)
```




    'CCACACCACA'




```python
seq_client.get_sequence("6681ac2f62509cfc220d78751b8dc524", start=0, end=50)
```




    'CCACACCACACCCACACACCCACACACCACACCACACACCACACCACACC'



You can also hit the `{digest}/metadata` and `service_info` API endpoints described in the refget API specification:


```python
seq_client.get_metadata("6681ac2f62509cfc220d78751b8dc524")
```




    {'metadata': {'id': '6681ac2f62509cfc220d78751b8dc524',
      'md5': '6681ac2f62509cfc220d78751b8dc524',
      'trunc512': '959cb1883fc1ca9ae1394ceb475a356ead1ecceff5824ae7',
      'ga4gh': 'SQ.lZyxiD_ByprhOUzrR1o1bq0ezO_1gkrn',
      'length': 230218,
      'aliases': []}}




```python
seq_client.service_info()
```




    {'id': 'refget.infra.ebi.ac.uk',
     'name': 'Refget server',
     'type': {'group': 'org.ga4gh', 'artifact': 'refget', 'version': '2.0.0'},
     'description': None,
     'organization': {'name': 'EMBL-EBI', 'url': 'https://ebi.ac.uk/'},
     'contactUrl': None,
     'documentationUrl': None,
     'createdAt': None,
     'updatedAt': None,
     'environment': None,
     'version': '1.0.1',
     'refget': {'circular_supported': False,
      'subsequence_limit': None,
      'algorithms': ['md5', 'ga4gh', 'trunc512'],
      'identifier_types': None}}



## Error handling

When requesting a sequence that doesn't exist, a compliant server should return a 404 error. The client will raise a `ConnectionError` if all URLs fail:

Note: Some servers may return different error codes (e.g., 500) for invalid digests. The client handles this by trying all configured URLs before failing.


```python
seq_client.get_sequence('BogusDigest')
```

    All URLs failed:
    Error from https://beta.ensembl.org/data/refget: 404 Client Error: Not Found for url: https://beta.ensembl.org/data/refget/sequence/BogusDigest


<div class="admonition success">
  <p class="admonition-title">Summary</p>
  <ul>
    <li><code>SequenceClient(urls)</code> connects to a remote refget sequences API</li>
    <li><code>client.get_sequence(digest)</code> retrieves sequences, with optional <code>start</code>/<code>end</code> positions</li>
    <li><code>client.get_metadata(digest)</code> returns sequence length and aliases</li>
  </ul>
</div>