{"id":34701758,"url":"https://github.com/hubmapconsortium/antibody-api","last_synced_at":"2026-01-17T16:32:48.462Z","repository":{"id":41830784,"uuid":"371143659","full_name":"hubmapconsortium/antibody-api","owner":"hubmapconsortium","description":"API for the Antibody DB.","archived":false,"fork":false,"pushed_at":"2026-01-12T19:18:18.000Z","size":17928,"stargazers_count":0,"open_issues_count":13,"forks_count":0,"subscribers_count":15,"default_branch":"main","last_synced_at":"2026-01-13T00:42:06.720Z","etag":null,"topics":["ot2od030545"],"latest_commit_sha":null,"homepage":"https://avr.xconsortia.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hubmapconsortium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-26T19:12:58.000Z","updated_at":"2026-01-12T19:17:05.000Z","dependencies_parsed_at":"2023-02-19T10:45:43.849Z","dependency_job_id":"f71c1c41-52f8-472c-97d2-9f2eb687b0ae","html_url":"https://github.com/hubmapconsortium/antibody-api","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/hubmapconsortium/antibody-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fantibody-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fantibody-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fantibody-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fantibody-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hubmapconsortium","download_url":"https://codeload.github.com/hubmapconsortium/antibody-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hubmapconsortium%2Fantibody-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28511868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ot2od030545"],"created_at":"2025-12-24T22:52:58.118Z","updated_at":"2026-01-17T16:32:48.448Z","avatar_url":"https://github.com/hubmapconsortium.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AVR/antibody-api\n\nThis information will help you get the Antibody API up in running whether locally or on an environment.\n\n### GUI\n\nThe Antibody API GUI should be running on the following environments, and is available at:\n[Prod](https://avr.hubmapconsortium.org/),\n[Dev](https://avr.dev.hubmapconsortium.org/).\n\n### Status\n\nThe status of each environment is available at:\n[Prod](https://avr.hubmapconsortium.org/status),\n[Dev](https://avr.dev.hubmapconsortium.org/status).\n\n## Build and Deploy Workflow\nThese are the steps used to build, publish a Docker image, and then deploy it.\n\nBefore doing so you will need to follow the steps outlined in the section \"Antibody API Configuration Changes\"\nto configure the server, and the instructions in the section\n\"Using the SearchAPI instead of directly reading from Elastic Search\" to properly\nconfigure the Search API server to handle queries from the Antibody API.\n\nLocal deployment instructions for testing purposes are found in the Section \"Local Deployment\".\n\n### Build Docker Image\n\nIn building a deployment version of the image, specify a version tag.\nYou can see the previous version tags at [DockerHub Antibody APi](https://github.com/hubmapconsortium/antibody-api/releases/).\n````bash\n$ ./generate-build-version.sh\n$ docker build -t hubmap/antibody-api:\u003cVERSION\u003e .\n````\n\n### Deploy DEV VM\n\n````bash\n$ export ANTIBODY_API_VERSION=\u003cold-version\u003e; docker compose -f docker-compose.deployment.yml down --rmi all\n$ export ANTIBODY_API_VERSION=\u003cnew-version\u003e; docker compose -f docker-compose.deployment.yml up -d --no-build\n````\n\n## Local Deployment\n\nFor local development you will also need to install the [Search API from GitHub](https://github.com/hubmapconsortium/search-api).\nSee \"Using the SearchAPI instead of directly reading from Elastic Search\" for configuration information.\n\nBefore deploying the server you will need to configure it.\nPlease follow the steps outlined in the section \"Antibody API Configuration Changes\"\n\nTo shutdown and remove all containers if anything is running by executing the following:\n```bash\n$ ./scripts/run_local.sh down -v --rmi all\n```\n\nThen restore the Docker Containers, Networks, and Volumes can be done by executing the following script.\nIf you delete one of the Docker images (say the \"antibody-api_web-1 container) this will rebuild and restart it.\n```bash\n$ ./scripts/run_local.sh\n```\n\nYou may need to rebuild an empty database if the schema has change or if no schema exists.\n```bash\n$ ./scripts/create_empty_db_local.sh\n```\n\nYou will need to manually create the tables on the PostgreSQL database that is running in the container.\nThe user, password, and database definitions are found in `server/antibodyapi/default_config.py`,\nand for deployment should be overwritten in `instance/app.conf` (which is not kept in the repo).\nThis is done by accessing the database through the command line 'psql' command.\n```bash\nif [[ `which psql; echo $?` -ne 0 ]] ; then\n  brew install postgresql\nfi\npsql -h localhost -U postgres -d antibodydb -a -f ./development/postgresql_init_scripts/create_tables.sql \n```\n\nYou will be asked for the database password which you will find in the `instance/app.conf` file in the entry `DATABASE_PASSWORD`.\n\nWhen running locally you will need to start an instance of `search-api`\non your development machine because one is not included in the docker-config\npackages. To do this please see the section `Startup the Search API on localhost`.\n\nOnce the data is loaded you can use the antibody search api located at [http://localhost:5000/](http://localhost:5000)\n\nNow that the tables exist, you will need to load some data into them.\nFind the file `server/manual_test_files/README.md`, and execute the sequence in the 'Manual test for 'upload' (.tsv only)' section.\nThis will upload the data to the PostgreSQL database and to Elastic Search.\n\nTo see the data that is in Elastic Search directly you can execute the following.\nThe index (here 'hm_antibodies') is defined in `server/antibodyapi/default_config.py` as ANTIBODY_ELASTICSEARCH_INDEX.\n```bash\nif [[ `which curl; echo $?` -ne 0 ]] ; then\n  brew install curl\nfi\ncurl -H 'Content-Type: application/json' -X GET http://localhost:9200/hm_antibodies/_search?pretty\n```\n\nThis should match the data in the database. Taking one of the \"antibody_uuid\" entries returned by Elastic Search above.\n```bash\n$ psql -h localhost -U postgres -d antibodydb -c \"SELECT * from antibodies where antibody_uuid='ec53fcf7bf49db0a100ff5b218cf82a3'\"\n```\n\nYou can ssh to the local container as `root` with...\n```bash\n$ docker ps\nCONTAINER ID   IMAGE            ...\n7d5c3d228284   antibody-api_web ...\n$ docker exec -it \u003cCONTAINER_ID\u003e /bin/sh\n/app/server # id\nuid=0(root) gid=0(root) groups=0(root)\n```\n\nTo load a utility (e.g., curl) onto the container use...\n```bash\n# apk add curl\n```\n\n## Deleting and Restoring the Elastic Search Index\n\nThe PostgreSQL database is used as the stable store for all of the data input,\nand Elastic Search is used as a method to query it. If you need to move a database\nfrom one server to another you can restore the Elastic Search Index as follows.\nThe following shows how to do this using the Docker containters spun up using\n`./scripts/run_local.sh` (see `./scripts/README.md` for more information on these scripts).\n\nFirst query on the index and see if data exists as follows:\n```bash\n$ curl -H 'Content-Type: application/json' -X GET http://localhost:9200/hm_antibodies/_search?pretty\n```\nYou should get an error telling you that the index does not exist, or you should get data.\n\nTo test the restore, you can delete the Elastic Search Index using the following:\n```bash\n$ curl -H 'Content-Type: application/json' -X DELETE http://localhost:9200/hm_antibodies\n```\n\nRestore the Elastic Search Index from the PostgreSQL database using the \nMSAPI endpoint `/restore` on the antibody-api server as follows:\n```bash\n$ curl -H 'Content-Type: application/json' -X PUT http://localhost:5000/restore_elasticsearch\n```\n\nAt this point the query on the Elastic Search index should return a subset of\nthe data found in the database (see `./scripts/compare_db_with_index.py`).\n\n## Using the SearchAPI instead of directly reading from Elastic Search\n\nThe file `./server/antibodyapi/default_config.py` contains the variable `QUERY_ELASTICSEARCH_DIRECTLY`.\nIf this variable is set to True, then searches from the UI will use Elastic Search directly.\nIf False then UI search queries will take place through the Search API.\n\nThe following describes how to set this up for testing.\n\n### Search API Configuration Changes\n\nAdd the following to the end of the file `search-api:src/instance/search-config.yaml`.\nThis will add the Antibody API Elastic Search index to Search API.\nNote that the 'url' corresponds to the instance of ElasticSearch that is running in the Docker container.\nFor running in the various environments, set the 'url' appropriately.\n```commandline\n  hm_antibodies:\n    active: true\n    reindex_enabled: false\n    public: hm_antibodies\n    private: hm_antibodies\n    elasticsearch:\n      url: 'http://localhost:9200'\n```\n\n`serch-api:/src/instance/app.cfg`: The Elastic Search server should point to the instance running in Docker,\nand the Entity API should be in the same space as the Antibody API; in this case 'test'.\nYou will also have to set the `APP_CLIENT_ID`, `APP_CLIENT_SECRET`, `GLOBUS_HUBMAP_READ_GROUP_UUID`, and\n`GLOBUS_HUBMAP_DATA_ADMIN_GROUP_UUID` appropriately.\n\nThese are not saved in GitHub for security reasons.\n```commandline\nELASTICSEARCH_URL = 'http://localhost:9200'\nENTITY_API_URL = 'https://entity-api.dev.hubmapconsortium.org'\n```\n\n### Startup the Search API on localhost\n\nIn the Search API repository consult the file './local-development-instructions.md'.\n```bash\n$ source venv-hm-search-api/bin/activate\n$ python3 src/app.py\n```\n\nWhen you start the SearchAPI on localhost it will tell you what port it's running on in the console logs.\nYou will need this information to set the Antibody API SEARCH_API_BASE port below. \n```commandline\n[2022-01-25 13:45:19] INFO in _internal:225:  * Running on http://10.0.0.14:5005/ (Press CTRL+C to quit)\n```\n\n### Antibody API Configuration Changes\n\nantibody-api:/server/antibodyapi/default_config.py: Contains the variable 'QUERY_ELASTICSEARCH_DIRECTLY'.\nIf this variable is set to True, then searches from the UI will use Elastic Search directly.\nIf False then UI search queries will take place through the Search API.\n\nYou will need to specify the FLASK_APP_BASE_URI because of OAUTH2 redirection to the original application from the Gateway.\n\nUse the local ELASTICSEARCH_SERVER, and SEARCH_API_BASE.\nSet the UUID_API_URL (used to get the unique identifier for the antibodies),\nand the INGEST_API_URL (used to store the .pdf files) the in test space (same space as Search API above).\nUse 'host.docker.internal' to access the Search API running on localhost,\nand the port from the INFO line above when the Search API is started (e.g., \"Running on\" port).\n\nMake sure that both 'antibody-api:/instance/app.conf' and 'search-api/src/instance/app.cfg'\nare using the same environment ('test' is suggested).\n```commandline\nFLASK_APP_BASE_URI = 'http://localhost:5000/'\n\n# This is the name of the container in the docker-compose file.\nELASTICSEARCH_SERVER =   'http://elasticsearch'\nSEARCH_API_BASE =        'http://host.docker.internal:5005'\nUUID_API_URL =           'https://uuid-api.test.hubmapconsortium.org'\nINGEST_API_URL =         'https://ingest-api.test.hubmapconsortium.org'\n\nANTIBODY_ELASTICSEARCH_INDEX = 'hm_antibodies'\nQUERY_ELASTICSEARCH_DIRECTLY = False\n```\n\n### Startup the Antibody API processes in Docker\n\nIf you have not already started the Antibody API do so (see /scripts/README.md).\n\n\n### Accessing the Search API from the container\n\nYou should be able to access the Search-API from the container with the following:\n```bash\n$ docker exec -it antibody-api_db_1 bash\n$ apt update; apt install curl\n$ curl -H 'Content-Type: application/json' -d '{\"query\": {\"match_all\": {}}}' -X POST  http://host.docker.internal:5005/hm_antibodies/search\n{\"_shards\":{\"failed\":0,\"skipped\":0,\"successful\":1,\"total\":1}, ... , \"timed_out\":false,\"took\":1}\n```\n\nIf you get an error message like below .\n```bash\n$ curl -H 'Content-Type: application/json' -d '{\"query\": {\"match_all\": {}}}' -X POST  http://host.docker.internal:5005/hm_antibodies/search\n{\"error\":{\"index\":\"hm_antibodies\",\"index_uuid\":\"_na_\",\"reason\":\"no such index [hm_antibodies]\"\n```\nIf you get this message you will need to load some data (see 'server/manual_test_files/README.md' section 'Manual test for 'upload' (.tsv only)').\n\n### Accessing the Antibody API GUI\n\nOpen the following web page\n```commandline\nhttp://localhost:5000\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhubmapconsortium%2Fantibody-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhubmapconsortium%2Fantibody-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhubmapconsortium%2Fantibody-api/lists"}