.. _endpoint_list:

STARS API Endpoints
===================

Introduction
------------

A detailed list of all the STARS API RESTful endpoints, along with example input and output.
There are three major interfaces: Credits, Submissions, and Institutions. All
endpoints start with a prefix of the following format::

/api/<api_version>/<interface>/

For example, accessing the Credits interface for Version 0.1 of the API would look
like this::
	/api/0.1/credits/...

Currently the STARS API supports several output formats:

 * json
 * jsonp
 * yaml
 * xml
 * html

To select a particular format use the format get parameter::

	/api/0.1/credits/creditset/?format=json

All examples use ``json``.

API Key Authentication
----------------------

Once you have obtained an API key from AASHE (by emailing stars@aashe.org), you
can either specify an Authorization header or pass the username/api_key
combination as GET/POST parameters. Examples::

	# As a header
	# Format is ``Authorization: ApiKey <username>:<api_key>
	Authorization: ApiKey my_user_name:204db7bcfafb2deb7506b89eb3b9b715b09905c8

	# As GET params
	http://127.0.0.1:8000/api/v1/entries/?username=my_user_name&api_key=204db7bcfafb2deb7506b89eb3b9b715b09905c8
	
All Endpoints
-------------

.. toctree::
	:maxdepth: 2

	credits_api_endpoints
	institutions_api_endpoints
	submissions_api_endpoints