Skip to content

Commit

Permalink
initial commit to include TS API documentation on readthedocs
Browse files Browse the repository at this point in the history
  • Loading branch information
@martenson
martenson committed Aug 6, 2015
1 parent 9838d93 commit a781f0a
Show file tree
Hide file tree
Showing 4 changed files with 116 additions and 98 deletions.
72 changes: 72 additions & 0 deletions doc/source/api/guidelines.rst
View file
@@ -0,0 +1,72 @@
API Design Guidelines
=====================

The following section outlines guidelines related to extending and/or modifing
the Galaxy API. The Galaxy API has grown in an ad-hoc fashion over time by
many contributors and so clients SHOULD NOT expect the API will conform to
these guidelines - but developers contributing to the Galaxy API SHOULD follow
these guidelines.

- API functionality should include docstring documentation for consumption
by readthedocs.org.
- Developers should familiarize themselves with the HTTP status code definitions
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. The API responses
should properly set the status code according to the result - in particular
2XX responses should be used for successful requests, 4XX for various
kinds of client errors, and 5XX for the errors on the server side.
- If there is an error processing some part of request (one item in a list
for instance), the status code should be set to reflect the error and the
partial result may or may not be returned depending on the controller -
this behavior should be documented.
- API methods should throw a finite number of exceptions
(defined in :doc:`galaxy.exceptions`) and these should subclass
`MessageException` and not paste/wsgi HTTP exceptions. When possible,
the framework itself should be responsible catching these exceptions,
setting the status code, and building an error response.
- Error responses should not consist of plain text strings - they should be
dictionaries describing the error and containing the following::

{
"status_code": 400,
"err_code": 400007,
"err_msg": "Request contained invalid parameter, action could not be completed.",
"type": "error",
"extra_error_info": "Extra information."
}

Various error conditions (once a format has been chosen and framework to
enforce it in place) should be spelled out in this document.
- Backward compatibility is important and should be maintained when possible.
If changing behavior in a non-backward compatibile way please ensure one
of the following holds - there is a strong reason to believe no consumers
depend on a behavior, the behavior is effectively broken, or the API
method being modified has not been part of a tagged dist release.

The following bullet points represent good practices more than guidelines, please
consider them when modifying the API.

- Functionality should not be copied and pasted between controllers -
consider refactoring functionality into associated classes or short of
that into Mixins (http://en.wikipedia.org/wiki/Composition_over_inheritance)
or into Managers (:doc:`galaxy.managers`).
- API additions are more permanent changes to Galaxy than many other potential
changes and so a second opinion on API changes should be sought. (Consider a
pull request!)
- New API functionality should include functional tests. These functional
tests should be implemented in Python and placed in
`test/functional/api`. (Once such a framework is in place - it is not
right now).
- Changes to reflect modifications to the API should be pushed upstream to
the BioBlend project if possible.

Longer term goals/notes.

- It would be advantageous to have a clearer separation of anonymous and
admin handling functionality.
- If at some point in the future, functionality needs to be added that
breaks backward compatibility in a significant way to a component used by
the community - a "dev" variant of the API will be established and
the community should be alerted and given a timeframe for when the old
behavior will be replaced with the new behavior.
- Consistent standards for range-based requests, batch requests, filtered
requests, etc... should be established and documented here.
74 changes: 1 addition & 73 deletions doc/source/api_doc.rst
View file
Expand Up @@ -205,78 +205,6 @@ used in the web form, like 'link_data_only' and etc.

The request and response format should be considered alpha and are subject to change.

API Design Guidelines
=====================

The following section outlines guidelines related to extending and/or modifing
the Galaxy API. The Galaxy API has grown in an ad-hoc fashion over time by
many contributors and so clients SHOULD NOT expect the API will conform to
these guidelines - but developers contributing to the Galaxy API SHOULD follow
these guidelines.

- API functionality should include docstring documentation for consumption
by readthedocs.org.
- Developers should familiarize themselves with the HTTP status code definitions
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html. The API responses
should properly set the status code according to the result - in particular
2XX responses should be used for successful requests, 4XX for various
kinds of client errors, and 5XX for the errors on the server side.
- If there is an error processing some part of request (one item in a list
for instance), the status code should be set to reflect the error and the
partial result may or may not be returned depending on the controller -
this behavior should be documented.
- API methods should throw a finite number of exceptions
(defined in :doc:`galaxy.exceptions`) and these should subclass
`MessageException` and not paste/wsgi HTTP exceptions. When possible,
the framework itself should be responsible catching these exceptions,
setting the status code, and building an error response.
- Error responses should not consist of plain text strings - they should be
dictionaries describing the error and containing the following::

{
"status_code": 400,
"err_code": 400007,
"err_msg": "Request contained invalid parameter, action could not be completed.",
"type": "error",
"extra_error_info": "Extra information."
}

Various error conditions (once a format has been chosen and framework to
enforce it in place) should be spelled out in this document.
- Backward compatibility is important and should be maintained when possible.
If changing behavior in a non-backward compatibile way please ensure one
of the following holds - there is a strong reason to believe no consumers
depend on a behavior, the behavior is effectively broken, or the API
method being modified has not been part of a tagged dist release.

The following bullet points represent good practices more than guidelines, please
consider them when modifying the API.

- Functionality should not be copied and pasted between controllers -
consider refactoring functionality into associated classes or short of
that into Mixins (http://en.wikipedia.org/wiki/Composition_over_inheritance)
or into Managers (:doc:`galaxy.managers`).
- API additions are more permanent changes to Galaxy than many other potential
changes and so a second opinion on API changes should be sought. (Consider a
pull request!)
- New API functionality should include functional tests. These functional
tests should be implemented in Python and placed in
`test/functional/api`. (Once such a framework is in place - it is not
right now).
- Changes to reflect modifications to the API should be pushed upstream to
the BioBlend project if possible.

Longer term goals/notes.

- It would be advantageous to have a clearer separation of anonymous and
admin handling functionality.
- If at some point in the future, functionality needs to be added that
breaks backward compatibility in a significant way to a component used by
the community - a "dev" variant of the API will be established and
the community should be alerted and given a timeframe for when the old
behavior will be replaced with the new behavior.
- Consistent standards for range-based requests, batch requests, filtered
requests, etc... should be established and documented here.

.. include:: api/guidelines.rst

.. include:: lib/galaxy.webapps.galaxy.api.rst
49 changes: 24 additions & 25 deletions doc/source/index.rst
View file
Expand Up @@ -8,41 +8,29 @@ transparent computational biomedical research.
- *Reproducible:* Galaxy captures information so that any user can repeat and understand a complete computational analysis.
- *Transparent:* Users share and publish analyses via the web and create Pages, interactive, web-based documents that describe a complete analysis.

Two copies of the Galaxy code doumentation are published by the Galaxy Project
Things to know:

- Galaxy-Dist_: This describes the code in the `most recent official release`_ of Galaxy.
- Galaxy-Central_: Describes the `current code in the development branch`_ of Galaxy. This is the latest checkin, bleeding edge version of the code. The documentation should never be more than an hour behind the code.
- There are multiple choices_ when it comes to using Galaxy.
- You can explore the `current code in the development branch`_ on GitHub.
- This documentation is hosted at readthedocs_.

Both copies are hosted at ReadTheDocs_, a publicly supported web site for hosting project documentation.
For more information on the Galaxy Project, please visit the `project home page`_.

If you have your own copy of the Galaxy source code, you can also generate your own version of this documentation:

::

$ cd doc
$ make html

The generated documentation will be in ``doc/build/html/`` and can be viewed with a web browser. Note that you will need to install Sphinx and a fair number of module dependencies before this will produce output.

.. _Galaxy: http://galaxyproject.org/
.. _Galaxy-Dist: https://galaxy-dist.readthedocs.org/
.. _most recent official release: https://bitbucket.org/galaxy/galaxy-dist
.. _Galaxy-Central: https://galaxy-central.readthedocs.org/
.. _current code in the development branch: https://bitbucket.org/galaxy/galaxy-central
.. _ReadTheDocs: https://readthedocs.org/


For more on the Galaxy Project, please visit the `project home page`_.

.. _project home page: http://galaxyproject.org/
.. _Galaxy: http://galaxyproject.org
.. _choices: https://wiki.galaxyproject.org/BigPicture/Choices
.. _current code in the development branch: https://github.com/galaxyproject/galaxy
.. _readthedocs: http://galaxy.readthedocs.org
.. _project home page: http://galaxyproject.org


Contents
========
.. toctree::
:maxdepth: 5

API Documentation <api_doc>
Galaxy API Documentation <api_doc>

Tool Shed API Documentation <ts_api_doc>

Application Documentation <lib/modules>

Expand All @@ -55,3 +43,14 @@ Indices and tables
* :ref:`modindex`
* :ref:`search`

Building this Documentation
==========================

If you have your own copy of the Galaxy source code, you can also generate your own version of this documentation:

::

$ cd doc
$ make html

The generated documentation will be in ``doc/build/html/`` and can be viewed with a web browser. Note that you will need to install Sphinx and a fair number of module dependencies before this will produce output.
19 changes: 19 additions & 0 deletions doc/source/ts_api_doc.rst
View file
@@ -0,0 +1,19 @@
Tool Shed API Documentation
***************************

Introduction
============
The Galaxy Tool Shed can be accessed programmatically using API described
here via shell scripts and other programs.
To interact with the API you first need to log in as your user, navigate
to the API Keys page in the User menu, and generate a new API key. This
key you have to attach to every request as a parameter. Example:

::

GET https://toolshed.g2.bx.psu.edu/api/repositories?q=fastq?key=SOME_KEY_HERE


.. include:: api/guidelines.rst

.. include:: lib/galaxy.webapps.tool_shed.api.rst

0 comments on commit a781f0a

Please sign in to comment.