This is the primary programming interface to the Coordinated Assessments tables. In order to actively use the API for testing or production, you will need an API key. You can get an API key by contacting https://api.streamnet.org
Here is an example usage:
https://api.streamnet.org/api/v1/users
The default format used by the API is JSON. In order to send or receive data in XML format, you must either include the request header (“ACCEPT: application/xml”) or append any URI with “.xml” (e.g. https://api.streamnet.org/api/v1/users.xml).
Users
Access your API key by passing your email and password as form fields or query parameters over HTTP Basic authentication. This will return an object
that contains the API key. You will need this key to make any other API calls.
| Action | Description |
|---|---|
| GET /api/v1/users | Fetch the metadata for your user account. |
Coordinated Assessments
Create, access, update, or delete data records collected for the Coordinated Assessments data sets.
TABLES
| Action | Description |
|---|---|
| GET /api/v1/ca/tables | Fetch the list of Coordinated Assessments data tables. |
| GET /api/v1/ca/tables/:id | Fetch the metadata for a single table (field names & types). This is the table schema. |
RECORDS
| Action | Description |
|---|---|
| GET /api/v1/ca | Fetch a list of records based on query parameters (see params below). |
| POST /api/v1/ca | Create a single record. |
| GET /api/v1/ca/:id | Fetch a single record. |
| PUT /api/v1/ca/:id | Update a single record. |
| DELETE /api/v1/ca/:id | Delete a single record. |
[Query Params]
| Param | Description |
|---|---|
| updated_since | Date since epoch in seconds: 2012-04-24 15:05:22 -0400 = 1335294322. Not required. |
| table_id | ID of the table the record is associated with. This is required for the GET record list action as well as the POST and PUT actions. For the GET action, include table_id as a form or query param. For PUT or POST, table_id must be included as a key of the object submitted in the body of the request along with the record_values object. See example below. |
| page | Integer of the page selected. By default, all requests are paginated to 1000 records per request. Not required. |
| per_page | Integer for the number of records per page. By default, all requests are paginated to the maximum value of 1000 records per request. Not required. |
| agency | This is the agency that submitted the record. You can designate one or more (comma-separated) agency acronyms: IDFG, WDFW, ODFW, CRITFC, CCT, NOAA. Can also be used to retrieve only records submitted with your API key by setting this value to your API key value. Not required. |
| record_values |
Must be present and an object (JSON or XML) in the body of the request for POST (insert) and PUT (update) actions. The keys of this object must reflect the keys (field names) in the table schema. Note that while the ID field is required for PUT actions, it is not required for POST actions as a new ID (as a GUID) will be generated if it is not included. If the ID field is submitted for POST actions, it must be a properly formatted GUID. All successful POST actions return the ID field in the return payload. For POST actions, all DES fields are required to be present in the object even if the values are NULL or empty. For PUT actions, only the ID and any fields to be updated are required in the object. Non-DES fields (e.g., “compilerrecordid”) can be included in either PUT or POST actions but are not required. |
Publishing Your Data
All records inserted by you are unpublished by default. You can insert, update, and delete records and test your system without any of your records showing on any output, including the CAX-EPA node, StreamNet, or the NOAA SPS web service.
Validations
Adding and updating CA records follows a strict set of requirements, including type & range validation and required fields based on the CA DES. Any validation errors will return a 422 and an object with a list of validation errors.
If you would like to validate your data before making any changes to the StreamNet database, you can include the header XValidate=true on any POST, PUT, or DELETE actions. If you do this, the actions will return the status code and any validation errors, but no changes will be made to the database.
Examples
Example validation response where three fields do not validate on a POST action:
{"error":{"msg":"data could not be processed",
"record_values":{
"Age1Juvs":"required for DES, but does not exist in the incoming record",
"HarvestAdj|length=9":"the length of this string value must be <= 3",
"Age2Juvs|value=seven":"this should be a decimal value"},
"params":{}}}
Example of the request body object in JSON, for POST and PUT actions:
{"table_id":"3613A357-258C-4615-927F-EB368C61E13E",
"record_values":{
"rperstype":"Adult recruits per adult spawners",
"recruitsalpha":"",
"age4adults":"",
"methodadjustments":"",
"esu_dps":"Lower Columbia River Coho Salmon ESU",
"recruitslowerlimit":"",
"nullrecord":false,
"metriclocation":"http://salmontracker.psmfc.org/summary/#/species=1
&run=2&esu=159/esu=159&metric=1&level=3/filter=159&start_year=1992&end_year=2013",
"recruitsmissing":false,
"contactphone":"541-757-5108",
"contactagency":"PSMFC",
"age8adults":"",
"compilernote":"PSMFC - TEST DATA",
"recruitsupperlimit":"",
"totalspawnersupperlimit":"",
"comments":"",
"contactpersonfirst":"Julie",
"yoy":"",
"rperslowerlimit":"",
"age5adults":"",
"age3adults":"",
"rpersupperlimit":"",
"rpersalpha":"",
"refid":"500021",
"lastupdated":"March, 12 2013 00:00:00",
"hatcheryspawnerslowerlimit":"",
"age9adults":"",
"tribharvest":"",
"hatcheryspawners":"",
"protmethurl":"http://salmontracker.psmfc.org/summary/#/species=1
&run=2&esu=159/esu=159&metric=1&level=3/filter=159&start_year=1992&end_year=2013",
"recruitsmissingexplanation":"",
"indicatorlocation":"http://salmontracker.psmfc.org/summary/#/species=1
&run=2&esu=159/esu=159&metric=1&level=3/filter=159&start_year=1992&end_year=2013",
"age11plusadults":"",
"id":"",
"contactpersonlast":"Firman",
"age10adults":"",
"age2juvs":"",
"broodyear":"1986",
"age6adults":"",
"commonpopname":"Sandy River",
"commonname":"Coho salmon",
"age2adults":"",
"recruitlocation":"Sandy River",
"contactemail":"GWilke@psmfc.org",
"sn_popid":"276",
"upddate":"June, 11 2013 00:00:00",
"metacomments":"Consult the contact person for the MeasureLocation data.",
"totalspawnerslowerlimit":"",
"totalspawners":"2558.0",
"run":"N/A",
"compiler":"GregWilke",
"datastatus":"Draft",
"nobroodstockremoved":"",
"recruits":"15428.0",
"measurelocation":"",
"age4plusjuvs":"",
"totalspawnersalpha":"",
"age3juvs":"",
"hatcheryspawnersalpha":"",
"hatcheryspawnersupperlimit":"",
"majorpopgroup":"Cascade",
"age7adults":"",
"age2juvs":"",
"compilerrecordid":"51017",
"cbfwapopname":"Sandy Coho",
"rpers":"6.03",
"esapopname":"Coho Salmon (Lower Columbia River ESU) - Sandy River",
"mainstemharvest":"",
"harvestadj":"",
"protmethdocumentation":"",
"spawnerlocation":"Sandy River",
"recoverydomain":"Willamette/Lower Columbia",
"protmethname":"coho-lc-adult-abundance.Design_5.doc"}}
