The StreamNet REST API allows for simple access to data sets using direct HTTP calls and exchanges data in JSON or XML format.

 

The base URI for the REST endpoint:

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.

 

SPS

Access data records collected for the NOAA SPS data set.

Action Description
GET /api/v1/sps Fetch a list of records based on query parameters (see params below).
GET /api/v1/sps/:id Fetch a single record.

 

[Query Params]

Param Description
updated_since Date since epoch in seconds: 2012-04-24 15:05:22 -0400 = 1335294322. Not required.
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.

 

Coordinated Assessments

Create, access, update, 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 retreive 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

By default, 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 th 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"}}