{"id":20486213,"url":"https://github.com/undp-data/ftss-api","last_synced_at":"2025-06-13T15:40:45.942Z","repository":{"id":260652609,"uuid":"881505491","full_name":"UNDP-Data/ftss-api","owner":"UNDP-Data","description":"A Python application written in FastAPI that powers UNDP Future Trends and System.","archived":false,"fork":false,"pushed_at":"2025-01-14T16:47:10.000Z","size":425,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-14T17:14:03.012Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ftss-api.azurewebsites.net","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UNDP-Data.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-10-31T17:53:33.000Z","updated_at":"2024-12-16T13:29:36.000Z","dependencies_parsed_at":"2024-11-01T16:27:48.558Z","dependency_job_id":"3afa2223-cee1-4c14-806f-c91c61d41c50","html_url":"https://github.com/UNDP-Data/ftss-api","commit_stats":null,"previous_names":["undp-data/ftss-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UNDP-Data%2Fftss-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UNDP-Data%2Fftss-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UNDP-Data%2Fftss-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UNDP-Data%2Fftss-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UNDP-Data","download_url":"https://codeload.github.com/UNDP-Data/ftss-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234152702,"owners_count":18787672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-15T16:35:45.096Z","updated_at":"2025-01-16T04:42:43.014Z","avatar_url":"https://github.com/UNDP-Data.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Future Trends and Signals System (FTSS) API\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/release/python-3110/)\n[![License](https://img.shields.io/github/license/undp-data/ftss-api)](https://github.com/undp-data/ftss-api/blob/main/LICENSE)\n[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336)](https://pycqa.github.io/isort/)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits\u0026logoColor=white)](https://conventionalcommits.org)\n[![Build and deploy Python app to Azure Web App](https://github.com/UNDP-Data/ftss-api/actions/workflows/azure-webapps-python.yml/badge.svg)](https://github.com/UNDP-Data/ftss-api/actions/workflows/azure-webapps-python.yml)\n\nThis repository hosts the API that powers the [UNDP Future Trends and Signals System](https://signals.data.undp.org) (FTSS).\nThe API is written using [FastAPI](https://fastapi.tiangolo.com) in Python and deployed on Azure App Services.\nIt serves as an intermediary between the front-end application and back-end database. The codebase is an open-source\nof the original project transferred from Azure DevOps.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Getting Started](#getting-started)\n- [Build and Test](#build-and-test)\n- [Contribute](#contribute)\n- [License](#license)\n- [Contact](#contact)\n\n## Introduction \n\nThe FTSS is an internal system built for the staff of the United Nations Development Programme, designed to capture\nsignals of change, and identify emerging trends within and outside the organisation. This repository hosts the back-end\nAPI that powers the platform and is accompanied by the [front-end repository](https://github.com/undp-data/fe-signals-and-trends).\n\nThe API is written and tested in Python `3.11` using [FastAPI](https://fastapi.tiangolo.com) framework. Database and \nstorage routines are implemented in an asynchronous manner, making the application fast and responsive. The API is\ndeployed on Azure App Services to development and production environments from `dev` and `main` branches\nrespectively. The API interacts with a PostgreSQL database deployed as an Azure Database for PostgreSQL instance. The\ninstance comprises `staging` and `production` databases. An Azure Blob Storage container stores images used as\nillustrations for signals and trends. The simplified architecture of the whole application is shown in the image below.\n\nCommits to `staging` branch in the front-end repository and `dev` branch in this repository trigger CI/CD pipelines for\nthe staging environment. While there is a single database instance, the data in the staging environment is isolated in\nthe `staging` database/schema separate from `production` database/schema within the same database instance. The same\nlogic applies to the blob storage – images uploaded in the staging environment are managed separately from those in the\nproduction environment.\n\n![Preview](images/architecture.drawio.svg)\n\nAuthentication in the API happens via tokens (JWT) issued by Microsoft Entra upon user log-in in the front-end\napplication. Some endpoints to retrieve approved signals/trends are accessible with a static API key \nfor integration with other applications. \n\n## Getting Started\n\nFor running the application locally, you can use either your local environment or a Docker container. Either way,\nclone the repository and navigate to the project directory first:\n\n```shell\n# Clone the repository\ngit clone https://github.com/undp-data/ftss-api\n\n# Navigate to the project folder\ncd ftss-api\n```\n\nYou must also ensure that the following environment variables are set up:\n\n```text\n# Authentication\nTENANT_ID=\"\u003cmicrosoft-entra-tenant-id\u003e\"\nCLIENT_ID=\"\u003capp-id\u003e\"\nAPI_KEY=\"\u003cstrong-password\u003e\" # for accessing \"public\" endpoints\n\n# Database and Storage\nDB_CONNECTION=\"postgresql://\u003cuser\u003e:\u003cpassword\u003e@\u003chost\u003e:5432/\u003cstaging|production\u003e\"\nSAS_URL=\"\"https://\u003caccount-name\u003e.blob.core.windows.net/\u003ccontainer-name\u003e?\u003csas-token\u003e\"\n\n# Azure OpenAI, only required for `/signals/generation`\nAZURE_OPENAI_ENDPOINT=\"https://\u003csubdomain\u003e.openai.azure.com/\"\nAZURE_OPENAI_API_KEY=\"\u003capi-key\u003e\"\n\n# Testing, only required to run tests, must be a valid token of a regular user\nAPI_JWT=\"\u003cjson-token\u003e\"\n```\n\n### Local Environment\n\nFor this scenario, you will need a connection string to the staging database.\n\n```bash\n# Create and activate a virtual environment.\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install core dependencies.\npip install -r requirements.txt\n\n# Launch the application.\nuvicorn main:app --reload\n```\n\nOnce launched, the application will be running at http://127.0.0.1:8000.\n\n### Docker Environment\n\nFor this scenario, you do not need a connection string as a fresh PostgreSQL instance will be\nset up for you in the container. Ensure that Docker engine is running on you machine, then execute:\n\n```shell\n# Start the containers\ndocker compose up --build -d\n```\n\nOnce launched, the application will be running at http://127.0.0.1:8000.\n\n# Build and Test\n\nThe codebase provides some basic tests written in `pytest`. To run them, ensure you have specified a valid token in your\n`API_JWT` environment variable. Then run:\n\n```shell\n# run all tests\n python -m pytest tests/\n \n # or alternatively\n make test\n```\n\nNote that some tests for search endpoints might fail as the tests are run against dynamically changing databases.\n\n# Contribute\n\nAll contributions must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).\nThe codebase is formatted with `black` and `isort`. Use the provided [Makefile](Makefile) for these\nroutine operations. Make sure to run the linter against your code.\n\n1. Clone or fork the repository\n2. Create a new branch (`git checkout -b feature-branch`)\n3. Make your changes\n4. Ensure your code is properly formatted (`make format`)\n5. Run the linter and check for any issues (`make lint`)\n6. Execute the tests (`make test`)\n7. Commit your changes (`git commit -m 'Add some feature'`)\n8. Push to the branch (`git push origin feature-branch`)\n9. Open a pull request to `dev` branch\n10. Once tested in the staging environment, open a pull requests to `main` branch\n\n## Contact\n\nThis project has been originally developed and maintained by [Data Futures Exchange (DFx)](https://data.undp.org) at UNDP.\nIf you are facing any issues or would like to make some suggestions, feel free to\n[open an issue](https://github.com/undp-data/ftss-api/issues/new/choose).\nFor enquiries about DFx, visit [Contact Us](https://data.undp.org/contact-us).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundp-data%2Fftss-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fundp-data%2Fftss-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundp-data%2Fftss-api/lists"}