NASA PDS Federated API

PDS strives to develop REST-ful web APIs for all online web applications, including data search and DOI management.

This repository is the entry point for the NASA PDS Federated API specifications (e.g. following OpenAPI standard) and their documentation.

Please visit our website at https://nasa-pds.github.io/pds-api/ for user documentation.

Prerequisites

Python 3

For PDF generation, basiclatex and accompanying libraries are needed

brew install basictex
sudo /Library/TeX/texbin/tlmgr update --self
sudo /Library/TeX/texbin/tlmgr install latexmk
sudo /Library/TeX/texbin/tlmgr install tex-gyre
sudo /Library/TeX/texbin/tlmgr install fncychap
sudo /Library/TeX/texbin/tlmgr install wrapfig
sudo /Library/TeX/texbin/tlmgr install capt-of
sudo /Library/TeX/texbin/tlmgr install framed
sudo /Library/TeX/texbin/tlmgr install needspace
sudo /Library/TeX/texbin/tlmgr install tabulary
sudo /Library/TeX/texbin/tlmgr install varwidth
sudo /Library/TeX/texbin/tlmgr install titlesec

Generate the user's documentation

Set the overall version (e.g. build number) in docs/source/conf.py

The OpenAPI yaml unresolved specifications are stored in the specs directory.

The naming of the specification are: PDS_APIs-{application}-{version}-swagger.yaml

For example: PDS_APIs-registry-1.0.0-swagger.yaml

To add a new specification or a new version of a specification:

Copy the OpenAPI Specification under the specs directory following the above filename convention.
Add a new entry for this file in docs/source/specifications.rst
In the file docs/source/conf.py add a section for the new specification in the redoc object.

Generate a PDF of the documentation.

cd docs/
make latexpdf
cp build/latex/pdsapis.pdf build/html/_static

Generate the Sphinx documentation:

pip install -e '.[dev]'

sphinx-build -b html docs/source docs/build/html

Code of Conduct

All users and developers of the NASA-PDS software are expected to abide by our Code of Conduct. Please read this to ensure you understand the expectations of our community.

Development

To develop this project, use your favorite text editor, or an integrated development environment with Python support, such as PyCharm.

Contributing

For information on how to contribute to NASA-PDS codebases please take a look at our Contributing guidelines.

CI/CD

The template repository comes with our two "standard" CI/CD workflows, stable-cicd and unstable-cicd. The unstable build runs on any push to main (± ignoring changes to specific files) and the stable build runs on push of a release branch of the form release/<release version>. Both of these make use of our GitHub actions build step, Roundup. The unstable-cicd will generate (and constantly update) a SNAPSHOT release. If you haven't done a formal software release you will end up with a v0.0.0-SNAPSHOT release (see NASA-PDS/roundup-action#56 for specifics).