Merge pull request #1 from datamade/text

Add pages for endpoints
datamade · May 30, 2017 · 411e05a · 411e05a
2 parents 608d571 + 4436312
commit 411e05a
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 5 deletions.
diff --git a/docs/endpoints.rst b/docs/endpoints.rst
@@ -0,0 +1,41 @@
+Endpoints
+=========
+
+The API contains eight different types of civic data. A unique endpoint represents each category:
+
+* bills
+
+* boundaries
+
+* divisions
+
+* events
+
+* jurisdictions
+
+* organizations
+
+* people
+
+* votes
+
+Independently filterable and searchable, the endpoints organize individual entries, each receiving a unique id. Displaying an entry reveals detailed information about a specified instance of civic data. 
+
+Elements of an Endpoint
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Each endpoint has two parts: (1) the listing pages, which contain general information on each entity, and (2) the detail pages, which contain all available data on a given entity. Some entries also contain the names and ids of related entities stored in different endpoints.
+
+a. To access the listing pages for a given endpoint, enter the following URL:
+
+::
+
+    ocd.datamade.us/{end_point_name}/
+
+The endpoint name should be one of the following categories listed above. Example:
+
+:: 
+
+    ocd.datamade.us/events
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,17 +3,30 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ocd-api-documentation's documentation!!!!!!!
-=======================================================
+=============================
+Open Civic Data Documentation
+=============================
+
+Overview
+========
+
+The primary goal of the Open Civic Data API (OCD) is to provide users with comprehensive, filterable database for exploring government data. The API allows users to search through information on legislation, politicians, governing bodies and divisions in an effort to make governments more transparent and accountable. The API is filtered using standard url query strings and returns data in an easily scrapable JSON format. DataMade uses the API to power many of its open government tools, including Chicago Councilmatic and LA Metro, but the database contains information on thousands of districts nationwide. The tool was created to help everyday citizens better understand their local governments and empower them to hold officials accountable to their constituents. 
+
+Requirements
+============
+
+The Open Civic Data API is readily accessible to anyone with an internet browser. It requires no special programs or installations to run. However, because results are presented in JSON format, it’s helpful to have some kind of JSON reader to organize the page in a more user-friendly way. (JSONview is a great extension for people using Chrome [https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en] or Firefox [https://addons.mozilla.org/en-Us/firefox/addon/jsonview/])
+
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
+
+   endpoints
+   querying_endpoints
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

diff --git a/docs/querying_endpoints.rst b/docs/querying_endpoints.rst
@@ -0,0 +1,19 @@
+Querying Endpoints
+==================
+
+Each of the API’s endpoints can be individually filtered and searched to provide more specific results. While users can search the API using basic URL query strings, OCD also supports a handful of more advanced queries, including certain Django URL Filters. (https://github.com/miki725/django-url-filter)
+
+Query basics
+~~~~~~~~~~~~
+
+i. URL query strings always begin with a question mark (?)
+
+::
+
+    http://ocd.datamade.us/bills/?{query string}
+    
+ii. If queries contain multiple parameters, separated them with an ampersand (&)
+
+::
+
+    i.e. http://ocd.datamade.us/bills/?{param1}&{param2}&{param3}