{
  "markdown": "# dc-api-v2\n\n[![Main API Build Status](https://github.com/nulib/dc-api-v2/actions/workflows/test-node.yml/badge.svg)](https://github.com/nulib/dc-api-v2/actions/workflows/test-node.yml) [![Chat API Build Status](https://github.com/nulib/dc-api-v2/actions/workflows/test-python.yml/badge.svg)](https://github.com/nulib/dc-api-v2/actions/workflows/test-python.yml)\n\n## Local development setup\n\n### `env.json`\n\nThe `env.json` file contains environment variable values for the lambda functions defined in the API for use in local development. You can create an `env.json` file containing the values to run the API against your dev data by running:\n\n```shell\nmake env.json\n```\n\nIf the file already exists, it will not be overwritten unless you include `-B` in the make command.\n\n## Running the API locally\n\nTo start the API in development mode, first make sure you have the correct version of the AWS SAM command line utility installed:\n\n```shell\nasdf install aws-sam-cli\n```\n\nThen run the following command:\n\n```shell\nmake serve\n```\n\nThe API will be available at:\n\n- `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002`\n  - Don't forget to [open port 3002](https://github.com/nulib/aws-developer-environment#convenience-scripts) if you want to access it remotely\n\n⚠️ Note the above URLs (which point to your local OpenSearch instance) need _full endpoints_ to resolve. For example:\n\n- `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/search`\n- `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/collections`\n\n[View supported endpoints](https://api.dc.library.northwestern.edu/docs/v2/spec/openapi.html) Questions? [View the production API documentation](https://api.dc.library.northwestern.edu/)\n\n### Chaos middleware\n\nThe API supports simulated network effects (errors and delays) for local testing via the `CHAOS_CONFIG` environment variable. If the variable is absent the middleware is disabled entirely.\n\nSet it to an inline JSON array:\n\n```shell\nexport CHAOS_CONFIG='[\n  { \"pattern\": \"/works/:id\", \"effect\": \"error\", \"status\": 500, \"chance\": 0.3 },\n  { \"pattern\": \"/auth/whoami\", \"effect\": \"delay\", \"ms\": 500 },\n  { \"pattern\": \"/file-sets/*\", \"effect\": \"delay\", \"ms\": [100, 800] }\n]'\n```\n\nOr set it to the path of a JSON file containing the same array:\n\n```shell\nexport CHAOS_CONFIG=/path/to/chaos.json\n```\n\nEach rule has a `pattern` (matched against the request path) and an `effect`:\n\n| Effect | Fields | Behavior |\n|--------|--------|----------|\n| `error` | `status` (HTTP status code), `chance` (0–1) | Returns `{\"error\":\"chaos\"}` with the given status; fires `chance * 100`% of the time |\n| `delay` | `ms` (number or `[min, max]`) | Pauses for the given number of milliseconds (random within range if a tuple) |\n\nAll matching rules are evaluated in order. Delay rules accumulate; an error rule short-circuits the request only when it fires — otherwise evaluation continues to the next rule.\n\n## Example workflows\n\n### Meadow\n\nView and edit information about a specific Work in the Index.\n\n1. Open a local Meadow instance.\n2. Find an `id` of a Work you'd like to inspect in the API.\n3. View JSON response at `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]`\n4. View IIIF Manifest JSON response at `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]?as=iiif`\n\n### IIIF content search\n\nIIIF Presentation responses expose [IIIF Content Search 2.0](https://iiif.io/api/search/2.0/) services for transcription annotations:\n\n- Work manifests include a `SearchService2` entry for `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]/search?as=iiif`\n- File set canvases include a `SearchService2` entry for `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/file-sets/[FILE_SET_ID]/search?as=iiif`\n\nTo search transcription text, include a non-empty `q` parameter:\n\n```shell\ncurl \"https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]/search?as=iiif&q=[QUERY]\"\ncurl \"https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/file-sets/[FILE_SET_ID]/search?as=iiif&q=[QUERY]\"\n```\n\nBoth endpoints return a IIIF `AnnotationPage` whose `items` target the matching work canvas or file set canvas. Requests without `as=iiif` or a non-empty `q` return `400`.\n\nFor help debugging/inspecting, JavaScript `console` messages are written to: `dc-api-v2/dc-api.log`\n\n### DC\n\nDevelop against changes to the API.\n\n1. Before starting the DC app, temporarily change the port number in `dc-nextjs/server.js` from default `3000` to something like `3003`.\n2. Open the port so it can be accessed in the browser.\n\n```\nsgport open all 3003\n```\n\n3. Point to the proxy URL and start DC app (in your `/environment/dc-nextjs` shell)\n\n```\nexport NEXT_PUBLIC_DCAPI_ENDPOINT=https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002\nbun run dev\n```\n\nAccess the app in a browser at: https://USER_PREFIX.dev.rdc.library.northwestern.edu:3003/\n\n## Running the API locally with state machine + lambdas (needed for AV download route)\n\n```shell\n# From the repo root\ncd dc-api-v2\n\n# Start the API + step function and associated lambdas\nmake start-with-step\n\n# Open a second terminal and create the state machine\nmake state-machine\n```\n\n## Deploying a development branch\n\nThere are two ways to deploy a development branch: `make deploy` and `make sync`. The differences are:\n\n- **Changes:** `deploy` deploys a static stack, and requires another `deploy` to update it. `sync` watches for\n  changes in realtime.\n- **Dependencies:** `deploy` uses the `apiDependencies` resource defined in the template for dependencies, while\n  `sync` uses the AWS SAM CLI's built-in development dependency logic.\n\nEither way, the resulting stack will be accessible at `https://dcapi-USER_PREFIX.rdc-staging.library.northwestern.edu`.\n\nAn existing `sync` stack can be reused by running `make sync` again, or by running `make sync-code` to only\nsync code changes (no infrastructure/template changes).\n\n### `samconfig.*.yaml`\n\nBoth methods involve a `samconfig.USER_PREFIX.yaml` file. This file, with default values, can be created by\nrunning (for example):\n\n```shell\nmake samconfig.mbk.yaml\n```\n\nThis will create a configuration to stand up the default stacks in both `deploy` mode (API, AV Download, and Chat) and\n`sync` mode (Chat only). To deploy a different combination of features, specify them using the `WITH` option:\n\n```shell\nmake samconfig.mbk.yaml WITH=API,DOCS\n```\n\nAvailable features are: `API`, `AV_DOWNLOAD`, `CHAT`, and `DOCS`. \n\n⚠️ Be **very** careful including the API in `sync` mode as every change within `/api` will take a long time to deploy.\n\nAs with the `env.json` file, `make` will not overwrite an existing file unless you include `-B`.\n\n### Tearing down a development stack\n\n```shell\nsam delete --stack-name dc-api-USER_PREFIX\n```\n\n## Writing Documentation\n\nAPI documentation is automatically regenerated and deployed on pushes to the staging and production branches. The documentation is in two parts:\n\n### Regular Docs\n\nThe `docs` directory contains a standard `mkdocs` project, which can be edited using the same tools and format as the main [Repository Documentation](http://docs.rdc.library.northwestern.edu/#contributing).\n\nIn a nutshell:\n\n1. Clone this project into a working directory (which you probably already have).\n2. Edit the Markdown files in the `docs/docs` directory.\n3. To run `mkdocs` locally and preview your work:\n   ```shell\n   sgport open all 8000\n   make serve-docs\n   ```\n   Docs will be accessible at http://USER_PREFIX.dev.rdc.library.northwestern.edu:8000/\n\n### OpenAPI/Swagger Docs\n\nWe also maintain an OpenAPI Specification under the docs directory in [`spec/openapi.yaml`](docs/docs/spec/openapi.yaml). When `mkdocs` is running, the Swagger UI can be found at http://USER_PREFIX.dev.rdc.library.northwestern.edu:8000/spec/openapi.html. Like the rest of the documentation, changes to the YAML will be immediately visible in the browser.\n\nThe existing spec files ([`openapi.yaml`](docs/docs/spec/openapi.yaml), [`types.yaml`](docs/docs/spec/types.yaml), and [`data-types.yaml`](docs/docs/spec/data-types.yaml)) are the best reference for understanding and updating the spec. It's especially important to understand how `openapi.yaml` uses the [`$ref` keyword](https://swagger.io/docs/specification/using-ref/) to refer to reusable elements defined in `types.yaml`, and how `types.yaml` pulls model schemas from `data-types.yaml`.\n\nFor an in-depth look, or to learn how to define things for which there aren't good examples in our spec, refer to the [full OpenAPI documentation](https://swagger.io/docs/specification/).\n\n#### Build Artifacts\n\n`openapi.html` renders the Swagger UI directly from the unmodified `openapi.yaml`. In addition, the build process generates a JSON copy of the spec using the [OpenAPI Generator CLI](https://openapi-generator.tech). In order to make sure the spec is valid before checking it in, run:\n\n```shell\nbun run validate-spec\n```\n\nThis check is also part of the CI test workflow, so an invalid spec file will cause the branch to fail CI.\n\n## DC API Typescript NPM package\n\nTypescript types for the schemas (Works, Collections, FileSets) are automatically published to the [nulib/dcapi-types](https://github.com/nulib/dcapi-types) repo on deploys.\n\n- If a deploy to the `deploy/staging` branch contains changes to the `docs/docs/spec/data-types.yaml` file, new types are generated and a commit is made to the `staging` branch of `nulib/dcapi`. This is intended to be for local testing by NUL devs against the private staging API.\n- If a deploy to production (`main` branch) contains changes to the `docs/docs/spec/data-types.yaml` file, new types are generated and a PR is opened into the `main` branch of `nulib/dcapi-types`. Also, an issue is created in `nulib/repodev_planning_and_docs` to review the PR and publish the types package (manually).\n\n## Versioning\n\nThe current API version is maintained in several different project files. To increment the version, use\n```\nmake version BUMP=<major|minor|patch>\n```\nIf you don't specify a `BUMP` value, the command will simply print the current version.\n",
  "bytes": 10150,
  "sha": "c2f79e561953cb601b5fa9d13250877696ef36c04e00da8cc60df26a83fa3130",
  "repo_slug": "nulib/dc-api-v2",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nulib_dc_api_042e79cf/readme"
}