Update Json Api Docs

Our json api docs had some api calls that did not work and some that could use some clarification between the processed and published dates. Some api calls repsonses were updated as well. refs #12306
nysenate · Feb 13, 2019 · e50712e · e50712e
1 parent ec52a37
commit e50712e
Show file tree

Hide file tree

Showing 55 changed files with 13,303 additions and 887 deletions.
diff --git a/docs/api/agendas.rst b/docs/api/agendas.rst
@@ -37,7 +37,6 @@ Returns a list of agenda ids in ascending order that occur in the given year
 
 **Examples**
 
-Request agenda 2 of session year 2017
 ::
    /api/3/agendas/2017
 
@@ -124,6 +123,9 @@ Search agendas across all years for a term
 +-----------+-----------------------------------------------------------------------------------------+
 | offset    | Start the results from offset                                                           |
 +-----------+-----------------------------------------------------------------------------------------+
++-----------+-----------------------------------------------------------------------------------------+
+| type      | Determine wether to use process date time or published date time                        |
++-----------+-----------------------------------------------------------------------------------------+
 
 
 **Examples**
@@ -145,12 +147,6 @@ Return a list of agenda ids that have changed during a specified date/time range
 
 .. note:: This api call gets updates in the last 7 days
 
-**Examples**
-
-Get all of the data in the last week
-::
-    /api/3/agendas/updates/
-
 **Usage**
 
 Get updates from the time specified to now
@@ -165,6 +161,7 @@ Get updates for all of the 2017 session
 
 **Usage**
 
+Get updates for a specified time range
 ::
     (GET) /api/3/agendas/updates/{from}/{to}
 
@@ -217,4 +214,4 @@ Return agenda digests that have changed during a specified date/time range
 
 Get updates for agenda 12 in 2017 from Jan 1st, 2017 to Dec 1st, 2017
 ::
-    /api/3/agendas/2017/12/updates/2017-01-01/2017-12-01
+    /api/3/agendas/2017/12/updates/2017-01-01/2017-12-01?type=published
diff --git a/docs/api/agg_updates.rst b/docs/api/agg_updates.rst
@@ -44,7 +44,7 @@ reprocess it's data to fix issues. By default the type is set to published.
 
 Get a detailed view of the first 50 agenda, bill, and calendar updates processed on March 17 2015
 ::
-    /api/3/updates/2015-03-17T00:00:00/2015-03-18T00:00:00?type=processed
+    /api/3/updates/2019-01-17T00:00:00/2019-01-18T00:00:00?type=processed
                     &content-type=AGENDA&content-type=BILL&content-type=CALENDAR
                     &detail=true&fields=true&limit=50
 
@@ -73,18 +73,20 @@ See the following pages for info on the unique updates responses for each conten
         "items" : [
           {
             "id" : {                        // Content identifier
-              "lawId" : "BNK",              // See content-specific updates pages
-              "activeDate" : "2014-09-26"
+              "basePrintNo": "S1948",         // See content-specific updates pages
+                "session": 2019,
+                "basePrintNoStr": "S1948-2019"
             },
-            "contentType" : "LAW",
-            "sourceId" : "DATABASE.LAW6",   // Id of the source that triggered the update
-            "sourceDateTime" : "2014-09-26T00:00",  // Published date of the source document
-            "processedDateTime" : "2015-03-18T10:48:35.023101", // Time when the update occurred
+            "contentType" : "BILL",
+            "sourceId": "2019-01-17-20.22.35.839069_SENMEMO_S01948.XML-1-SENMEMO",,   // Id of the source that triggered the update
+            "sourceDateTime" : "2019-01-17T20:22:35.839069",  // Published date of the source document
+            "processedDateTime" : "2019-01-17T20:26:24.673778", // Time when the update occurred
 
             // --- The following fields are returned only for update digests -------------------
-            "action" : "Insert",    // Update action (Insert|Update|Delete)
-            "scope" : "Law Tree",   // Designates which part of the content was updated
+            "action" : "Update",    // Update action (Insert|Update|Delete)
+            "scope" : "Bill Amendment",   // Designates which part of the content was updated
             "fields" : { }  // The updated fields, returned only if fields parameter is true
+            "fieldCount": 1
             // ---------------------------------------------------------------------------------
           },
           ...

diff --git a/docs/api/bills.rst b/docs/api/bills.rst
@@ -465,6 +465,14 @@ Get bill updates
 
 To identify which bills have received updates within a given time period you can use the bill updates api.
 
+
+.. warning::
+    There are two types of updates, 'processed' and 'published'.
+    Processed refers to the date that OpenLeg processed the data which is useful if you are trying to stay synchronized with OpenLeg.
+    Published refers to the date during which data was intended to be published.
+    This can differ from the processed date because OpenLeg can periodically reprocess it's data to fix issues.
+    By default the type is set to 'processed'.
+
 **Usage**
 
 List of bills updated during the given date/time range
@@ -501,16 +509,13 @@ List of bills updated since the given date/time
 |                |                      | Multiple formats can be requested.                     |
 +----------------+----------------------+--------------------------------------------------------+
 
-There are two types of updates, 'processed' and 'published'. Processed refers to the date that OpenLeg processed
-the data which is useful if you are trying to stay synchronized with OpenLeg. Published refers to the date during
-which data was intended to be published. This can differ from the processed date because OpenLeg can periodically
-reprocess it's data to fix issues. By default the type is set to 'processed'.
+.. warning:: By default the type is set to 'processed'. Ensure you have the right type in the api request so you receive the results you are looking for
 
 **Examples**
 
-Bills that were updated between November 1, 2014 and November 5, 2014
+Bills that were updated between February 13, 2019 8:00:00AM and February 13, 2019 at 10:55:48AM
 ::
-    /api/3/bills/updates/2014-11-01T00:00:00/2014-11-05T00:00:00
+    /api/3/bills/updates/2019-02-13T08:00:00/2019-02-13T10:55:48
 
 .. _bill-update-token-response:
 
@@ -519,23 +524,25 @@ Bills that were updated between November 1, 2014 and November 5, 2014
 .. code-block:: javascript
 
     {
-        "success": true,
-        "message": "",
-        "responseType": "base-bill-id-update-token list",
-        "total": 4,
-        "offsetStart": 1,
-        "offsetEnd": 4,
-        "limit": 50,
+        success: true,
+        message: "",
+        responseType: "update-token list",
+        total: 74,
+        offsetStart: 1,
+        offsetEnd: 50,
+        limit: 50,
         "result": {
             "items": [
                 {
-                    "id": {
-                        "basePrintNo": "A242",
-                        "session": 2013
+                   id: {
+                        basePrintNo: "S1826",
+                        session: 2019,
+                        basePrintNoStr: "S1826-2019"
                     },
-                    "sourceId": "SOBI.D141103.T092258.TXT-0-BILL",
-                    "sourceDateTime": "2014-11-03T09:22:58",
-                    "processedDateTime": "2014-12-17T16:54:24.065500"
+                    contentType: "BILL",
+                    sourceId: "2019-02-13-09.01.14.643609_LDSPON_S01826.XML-1-LDSPON",
+                    sourceDateTime: "2019-02-13T09:01:14.643609",
+                    processedDateTime: "2019-02-13T09:06:09.796845"
                 },
                 ... (truncated)
     }

diff --git a/docs/api/calendars.rst b/docs/api/calendars.rst
@@ -317,9 +317,9 @@ List of calendars updated during the given date/time range
 
 **Examples**
 
-Calendars that were updated between June 15th and June 20th of 2014
+Calendars that were updated between January 1st and January 20th of 2019
 ::
-    (GET) /api/3/calendars/updates/2014-06-15T00:00:00/2014-06-20T00:00:00
+    (GET) /api/3/calendars/updates/2019-01-01T00:00:00/2019-01-20T00:00:00
 
 .. _calendar-update-token-response:
 
@@ -339,19 +339,19 @@ Calendars that were updated between June 15th and June 20th of 2014
         "items" : [
           {
             "id" : {        // The year and calendar number of the updated calendar
-              "year" : 2014,
-              "calendarNumber" : 53
+              "year" : 2019,
+              "calendarNumber" : 1
             },
             // The id of the reference that triggered the update
-            "sourceId" : "SOBI.D140619.T221836.TXT-2-CALENDAR",
+            "sourceId" : "2019-01-14-15.55.39.563595_SENCAL_00001.XML-1-CALENDAR",
             // The publish date time of the reference source
-            "sourceDateTime" : "2014-06-19T22:18:36",
+            "sourceDateTime" : "2019-01-14T15:55:39.563595",
             // The date and time that the reference was processed
-            "processedDateTime" : "2014-12-15T15:21:07.002331"
+            "processedDateTime" : "2019-01-14T16:01:20.389704"
           },
           ... (truncated)
         ],
-        "size" : 4
+        "size" : 2
       }
     }
 
@@ -370,15 +370,17 @@ Get all updates for a calendar
 
 **Optional Params**
 
-+-----------+--------------------+--------------------------------------------------------+
-| Parameter | Values             | Description                                            |
-+===========+====================+========================================================+
-| order     | string (asc|desc)  | Order the results by update date/time                  |
-+-----------+--------------------+--------------------------------------------------------+
-| limit     | string             | (default 100) Limit the number of results              |
-+-----------+--------------------+--------------------------------------------------------+
-| offset    | number             | (default 1) Start results from offset                  |
-+-----------+--------------------+--------------------------------------------------------+
++-----------+----------------------+---------------------------------------------------------------+
+| Parameter | Values               | Description                                                   |
++===========+======================+===============================================================+
+| type      |(processed|published) | The type of bill update (see below for explanation)           |
++-----------+----------------------+---------------------------------------------------------------+
+| order     | string (asc|desc)    | Order the results by update date/time                         |
++-----------+----------------------+---------------------------------------------------------------+
+| limit     | string               | (default 100) Limit the number of results                     |
++-----------+----------------------+---------------------------------------------------------------+
+| offset    | number               | (default 1) Start results from offset                         |
++-----------+----------------------+---------------------------------------------------------------+
 
 **Examples**
 
@@ -388,7 +390,7 @@ Get updates for calendar 54 of 2014 that occurred between 9 AM and 5 PM on June
 
 .. _calendar-update-digest-response:
 
-**Response**
+**Response (type=published)**
 
 .. _`detailed update digests`:
 

diff --git a/docs/api/laws.rst b/docs/api/laws.rst
@@ -221,8 +221,8 @@ Search for law documents
 
 **Usage**
 ::
-    (GET) /api/3/laws/search           // Search across all law volumes
-    (GET) /api/3/laws/{lawId}/search   // Search within a specific law volume
+    (GET) /api/3/laws/search?term=           // Search across all law volumes
+    (GET) /api/3/laws/{lawId}/search?term=   // Search within a specific law volume
 
 **Required Params**
 
@@ -247,37 +247,6 @@ Search for law documents
 **Examples**
 ::
     /api/3/laws/search?term=chickens                            // Search all law volumes for the word 'chickens'
-    /api/3/laws/EDN/search?term=teacher&sort=activeDate:desc    // Search education law for documents containing 'teacher'
-                                                                // sorted by the activeDate in descending order.
-
-**Response**
-
-.. code-block:: javascript
-
-    {
-      "success" : true,
-      "message" : "",
-      "responseType" : "search-results list",
-      "total" : 178,                              // Total number of results
-      "offsetStart" : 1,                          // Pagination
-      "offsetEnd" : 25,
-      "limit" : 25,
-      "result" : {
-        "items" : [ {
-          "result" : {
-            "lawId" : "EDN",
-            "lawName" : "Education",
-            "locationId" : "3602",
-            "title" : "Apportionment of public moneys to school districts employing eight or more teachers",
-            "docType" : "SECTION",
-            "docLevelId" : "3602",
-            "activeDate" : "2014-12-26"
-          },
-          "rank" : 1,                             // Document score
-          "highlights" : {                        // Highlights contain the snippets where the match occurred.
-            "text" : [ " assistance of <em>teacher</em> aides or consultation\\nwith appropriate personnel. When a committee on special", " consultant <em>teacher</em>\\nservices, in accordance with regulations of the commissioner adopted for\\nsuch", " or indirect consultant <em>teacher</em>\\nservices, in accordance with regulations of the commissioner adopted", " under paragraph five of\\nsubdivision nineteen of this section;\\n  (11) <em>teacher</em> support payments made", ". Parent-<em>teacher</em> conferences or workshops. Notwithstanding any other\\nprovision of this section to" ]
-          }
-        }, .... (more results)
 
 Get law document updates
 ------------------------
@@ -328,7 +297,7 @@ All updates made on a specific body of law during a date/time range
 
 Global law updates
 ::
-    e.g. /api/3/laws/updates/2015-09-01T00:00:00/2015-10-01T00:00:00
+    e.g. /api/3/laws/updates/2015-09-01T00:00:00/2015-10-01T00:00:00?type=published
 
 .. code-block:: javascript
 
@@ -355,7 +324,7 @@ Global law updates
 
 Detailed law doc updates
 ::
-    e.g. /api/3/laws/updates/2015-09-01T00:00:00/2015-10-01T00:00:00?detail=true
+    e.g. /api/3/laws/updates/2015-09-01T00:00:00/2015-10-01T00:00:00?detail=true&type=published
          /api/3/laws/ABC/updates/
 
 .. code-block:: javascript
@@ -398,8 +367,8 @@ To see updates to the content of law documents, see `Get law document updates`_.
 List of laws with tree updates during the given date/time range
 ::
     /api/3/laws/tree/updates
-    /api/3/laws/tree/updates/{fromDateTime}
-    /api/3/laws/tree/updates/{fromDateTime}/{toDateTime}
+    /api/3/laws/tree/updates/{fromDateTime}?type=published
+    /api/3/laws/tree/updates/{fromDateTime}/{toDateTime}?type=published
 
 The fromDateTime and toDateTime should be formatted as the ISO Date Time format.
 For example December 10, 2014, 1:30:02 PM should be inputted as 2014-12-10T13:30:02.

diff --git a/docs/api/transcripts_floor.rst b/docs/api/transcripts_floor.rst
@@ -85,7 +85,7 @@ List 50 complete transcripts starting from 51
     /api/3/transcripts/2014?limit=50%offset=51&full=true
 List 10 complete transcripts sorted by increasing date
 ::
-    /api/3/transcripts/2014?limit=10&full=true&sort=dateTime:ASC
+    /api/3/transcripts/2014?limit=10&full=true
 
 **Response**
 

diff --git a/src/main/webapp/static/docs/doctrees/admin.doctree b/src/main/webapp/static/docs/doctrees/admin.doctree
diff --git a/src/main/webapp/static/docs/doctrees/agendas.doctree b/src/main/webapp/static/docs/doctrees/agendas.doctree
diff --git a/src/main/webapp/static/docs/doctrees/agg_updates.doctree b/src/main/webapp/static/docs/doctrees/agg_updates.doctree
diff --git a/src/main/webapp/static/docs/doctrees/bills.doctree b/src/main/webapp/static/docs/doctrees/bills.doctree
diff --git a/src/main/webapp/static/docs/doctrees/calendars.doctree b/src/main/webapp/static/docs/doctrees/calendars.doctree
diff --git a/src/main/webapp/static/docs/doctrees/committees.doctree b/src/main/webapp/static/docs/doctrees/committees.doctree
diff --git a/src/main/webapp/static/docs/doctrees/environment.pickle b/src/main/webapp/static/docs/doctrees/environment.pickle
diff --git a/src/main/webapp/static/docs/doctrees/index.doctree b/src/main/webapp/static/docs/doctrees/index.doctree
diff --git a/src/main/webapp/static/docs/doctrees/laws.doctree b/src/main/webapp/static/docs/doctrees/laws.doctree
diff --git a/src/main/webapp/static/docs/doctrees/members.doctree b/src/main/webapp/static/docs/doctrees/members.doctree
diff --git a/src/main/webapp/static/docs/doctrees/reference.doctree b/src/main/webapp/static/docs/doctrees/reference.doctree
diff --git a/src/main/webapp/static/docs/doctrees/search_api.doctree b/src/main/webapp/static/docs/doctrees/search_api.doctree
diff --git a/src/main/webapp/static/docs/doctrees/transcripts_floor.doctree b/src/main/webapp/static/docs/doctrees/transcripts_floor.doctree
diff --git a/src/main/webapp/static/docs/doctrees/transcripts_ph.doctree b/src/main/webapp/static/docs/doctrees/transcripts_ph.doctree
diff --git a/src/main/webapp/static/docs/html/.buildinfo b/src/main/webapp/static/docs/html/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: ed0c7729217c429bee4cc3aecb1d8fa7
+config: e0f11b5bbe254dff089b1fbb74c537fc
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/src/main/webapp/static/docs/html/_sources/agendas.rst.txt b/src/main/webapp/static/docs/html/_sources/agendas.rst.txt
@@ -37,7 +37,6 @@ Returns a list of agenda ids in ascending order that occur in the given year
 
 **Examples**
 
-Request agenda 2 of session year 2017
 ::
    /api/3/agendas/2017
 
@@ -124,6 +123,9 @@ Search agendas across all years for a term
 +-----------+-----------------------------------------------------------------------------------------+
 | offset    | Start the results from offset                                                           |
 +-----------+-----------------------------------------------------------------------------------------+
++-----------+-----------------------------------------------------------------------------------------+
+| type      | Determine wether to use process date time or published date time                        |
++-----------+-----------------------------------------------------------------------------------------+
 
 
 **Examples**
@@ -145,12 +147,6 @@ Return a list of agenda ids that have changed during a specified date/time range
 
 .. note:: This api call gets updates in the last 7 days
 
-**Examples**
-
-Get all of the data in the last week
-::
-    /api/3/agendas/updates/
-
 **Usage**
 
 Get updates from the time specified to now
@@ -165,6 +161,7 @@ Get updates for all of the 2017 session
 
 **Usage**
 
+Get updates for a specified time range
 ::
     (GET) /api/3/agendas/updates/{from}/{to}
 
@@ -217,4 +214,4 @@ Return agenda digests that have changed during a specified date/time range
 
 Get updates for agenda 12 in 2017 from Jan 1st, 2017 to Dec 1st, 2017
 ::
-    /api/3/agendas/2017/12/updates/2017-01-01/2017-12-01
+    /api/3/agendas/2017/12/updates/2017-01-01/2017-12-01?type=published