<commit_before>---
title: New Endpoint Tutorial
nav_order: 5
---

# Tutorial: Adding a new API endpoint

**Prerequisite:** this guide assumes that you have read the
[epidata development guide](epidata_development.md).

In this tutorial we'll create a brand new endpoint for the Epidata API:
`fluview_meta`. At a high level, we'll do the following steps:

1. understand the data that we want to surface
2. add the new endpoint to `api.php`
3. add the new endpoint to the various client libraries
4. write an integration test for the new endpoint
5. update API documentation for the new endpoint
6. run all unit and integration tests

# setup

Follow
[the backend guide](https://github.com/cmu-delphi/operations/blob/main/docs/backend_development.md)
and [the epidata guide](epidata_development.md) to install Docker and get your
workspace ready for development. Before continuing, your workspace should look
something like the following:

```bash
tree -L 3 .
```

```
.
└── repos
    ├── delphi
    │   ├── delphi-epidata
    │   ├── flu-contest
    │   ├── github-deploy-repo
    │   ├── nowcast
    │   ├── operations
    │   └── utils
    └── undefx
        ├── py3tester
        └── undef-analysis
```

# the data

Here's the requirement: we need to quickly surface the most recent "issue"
(epiweek of publication) for the existing [`fluview` endpoint](api/fluview.md).
The existing [`meta` endpoint](api/meta.md) already provides this,
however, it's _very_ slow, and it returns a bunch of unrelated data. The goal
is to extract the subset of metadata pertaining to `fluview` and return just that
data through a new endpoint.

Each row in the `fluview` table contains
[a lot of data](../src/ddl/fluview.sql), but we're particularly interested in
the following:

- latest publication date
- latest "issue", which is the publication epiweek
- total size of the table

# update the server

TODO sam

# update the client libraries

There are currently four client libraries. They all need to be updated to make
the new `fluview_meta` endpoint available to callers. The pattern is very
similar for all endpoints so that copy-paste will get you 90% of the way there.

`fluview_meta` is especially simple as it takes no parameters, and consequently,
there is no need to validate parameters. In general, it's a good idea to do
sanity checks on caller inputs prior to sending the request to the API. See
some of the other endpoint implementations (e.g. `fluview`) for an example of
what this looks like.

Here's what we add to each client:

- [`delphi_epidata.js`](../src/client/delphi_epidata.js)
    ```javascript
    // TODO sam
    Epidata.fluview_meta = function(callback) {
      var params;
      params = {
        'endpoint': 'fluview_meta'
      };
      return _request(callback, params);
    };
    ```

- [`delphi_epidata.d.ts`](../src/client/delphi_epidata.d.ts)
    ```typescript
    // TODO sam
    Epidata.fluview_meta = function(callback) {
      var params;
      params = {
        'endpoint': 'fluview_meta'
      };
      return _request(callback, params);
    };
    ```<commit_msg>docs: add new js client hints<commit_after>---
title: New Endpoint Tutorial
nav_order: 5
---

# Tutorial: Adding a new API endpoint

**Prerequisite:** this guide assumes that you have read the
[epidata development guide](epidata_development.md).

In this tutorial we'll create a brand new endpoint for the Epidata API:
`fluview_meta`. At a high level, we'll do the following steps:

1. understand the data that we want to surface
2. add the new endpoint to `api.php`
3. add the new endpoint to the various client libraries
4. write an integration test for the new endpoint
5. update API documentation for the new endpoint
6. run all unit and integration tests

# setup

Follow
[the backend guide](https://github.com/cmu-delphi/operations/blob/main/docs/backend_development.md)
and [the epidata guide](epidata_development.md) to install Docker and get your
workspace ready for development. Before continuing, your workspace should look
something like the following:

```bash
tree -L 3 .
```

```
.
└── repos
    ├── delphi
    │   ├── delphi-epidata
    │   ├── flu-contest
    │   ├── github-deploy-repo
    │   ├── nowcast
    │   ├── operations
    │   └── utils
    └── undefx
        ├── py3tester
        └── undef-analysis
```

# the data

Here's the requirement: we need to quickly surface the most recent "issue"
(epiweek of publication) for the existing [`fluview` endpoint](api/fluview.md).
The existing [`meta` endpoint](api/meta.md) already provides this,
however, it's _very_ slow, and it returns a bunch of unrelated data. The goal
is to extract the subset of metadata pertaining to `fluview` and return just that
data through a new endpoint.

Each row in the `fluview` table contains
[a lot of data](../src/ddl/fluview.sql), but we're particularly interested in
the following:

- latest publication date
- latest "issue", which is the publication epiweek
- total size of the table

# update the server

TODO sam

# update the client libraries

There are currently four client libraries. They all need to be updated to make
the new `fluview_meta` endpoint available to callers. The pattern is very
similar for all endpoints so that copy-paste will get you 90% of the way there.

`fluview_meta` is especially simple as it takes no parameters, and consequently,
there is no need to validate parameters. In general, it's a good idea to do
sanity checks on caller inputs prior to sending the request to the API. See
some of the other endpoint implementations (e.g. `fluview`) for an example of
what this looks like.

Here's what we add to each client:

- [`delphi_epidata.js`](../src/client/delphi_epidata.js)
    ```javascript
    // within createEpidataAsync
    return {
      BASE_URL: baseUrl || BASE_URL,
      //...
       /**
        * Fetch FluView metadata
        */
      fluview_meta: () => {
        return _request("fluview_meta", {});
      },
    };
    ```

- [`delphi_epidata.d.ts`](../src/client/delphi_epidata.d.ts)
    ```typescript
    export interface EpidataFunctions {
      // ...
      fluview_meta(callback: EpiDataCallback): Promise<EpiDataResponse>;
    }
    export interface EpidataAsyncFunctions {
      // ...
      fluview_meta(): Promise<EpiDataResponse>;
    }
    ```
{'fraction_non_alphanumeric': 0.0953285827395091, 'fraction_numerical': 0.0034837688044338875, 'mean_word_length': 3.404463040446304, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 6, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6788714', 'n_tokens_mistral': 1976, 'n_tokens_neox': 1824, 'n_words': 792}