REST Services and Reports

This section addresses:

:USDA #6:

Permit export of composition and analytical data and conversion of composition data to an application development format.

:USDA #10:

Permit assembly of ad hoc databases to suit individual needs.

:USDA #11:

Permit export of ad hoc data.

Table of Contents

Label project € data will be available to investigators € via REST € (Representational State Transfer) services. REST is a simple stateless architecture that runs over HTTP. REST service reads a designated Web page that contains an XML file in RDF format. XML/RDF file describes and includes label project data. Data is returned to investigator in JSON-LD € format.

../_images/$_02-core-12-rest-prov_.png

General Structure of REST API

Structure of a USDA REST conversation € :

Structure of the USDA REST API is:

http://usda.ars.gov/rest/<input specification>/<operation specification>/[<output specification>]/[<operation options>]

Example: “retrieve food description using food identifier [USDA_fid] and item number 2244”

http://usda.ars.gov/rest/food/USDA_fid/2244/JSON

Query Parameters: Input Specification

Input portion of URL tells service which records to use as subject of query.

This is further subdivided into two or more locations in URL “path” as follows:

query parameter title:
 input specification
query parameter domain:
 values may include food, compound, Nutrient Fact Panel (NFP) values and other inputs

For example:

                           1          2            3
<input_specification> = <domain>/<namespace>/<identifiers>


                2.1     2.2        2.3             2.4
1   <domain> = food | compound | NFP_values | <other inputs>


                                                   2.n.1                                              2.n.2
2.1    food domain <namespace> = USDA_fid | sourceid/<source name> | sourceall/<source name> | name | <xref>

2.2    compound domain <namespace> = PC_cid | name | inchikey | <xref>


                                                   2.n.3
2.3    NFP_values domain <namespace> = NFP_id | type/<NFP type> | sourceall/<source name> | activity/<activity column name> | {_to_be_specified_}

2.n.1     <source_name> = any valid Branded Food depositor name

2.n.2     <xref> = xref / {RegistryID | RN | NCBI_ProteinGI | NCBI_TaxonomyID }

2.n.3     <NFP_type> = all | panel | summary | {_to_be_specified_}

2.4    <other_inputs_to_be_specified_> = sources / [substance, assay] | conformers

3    <identifiers> = comma-separated list of positive integers (e.g. PC_cid, USDA_fid, NFP_id) or identifier strings (source, inchikey)

Query Parameters: Operation Specification

Operation part of URL tells service what to do with input records - such as to retrieve whole record or specific properties of a food.

Construction of this part of “path” will depend on Operation Specification. If no operation is specified, default is to retrieve entire record.

Available operations dependent on Input Specification. For example, certain operations are applicable only to foods, compounds and not NFP_values.

For example:

                                                         1.n.1                                                             1.n.2
1.1  food domain <operation_specification> = record | <food_property> | synonyms | PC_cids | NFP_values | classification | <xrefs> | description

1.n.1    <food_property> = property / [comma-separated list of property tags]

1.n.2    <xrefs> = xrefs / [comma-separated list of xrefs tags]

1.3  NFP domain <operation_specification> = record | NFP_ids | USDA_fids | PC_cids | description | summary | classification | xrefs

Query Parameters: Output Specification

Final portion of URL tells service what output format is desired.

Output format also can be specified in HTTP Accept field of request header.

For example:

<output:specification> = JSON | CSV | TXT

Request: Food property tables

Request properties for a food (USDA_fid) or compound (PC_cid).

http://usda.ars.gov/rest/food/USDA_fid/3114/property/JSON
Return food property table
Property Notes
to_be_specified to_be_specified
to_be_specified to_be_specified
Variation: Return Nutrient Fact Panel <NFP_type>
Options Allowed Values meaning
NFP_type all, primary, secondary Type of NFP to return given, USDA_fids, PC_cids
Variation: Return dates
Date Meaning
Deposition when an USDA_fid or NFP_id first appeared
Modification when an USDA_fid or NFP_id was last modified
Hold when an USDA_fid or NFP_id will be released
Creation when a USDA_fid or NFP_id first appeared
Deprecation when a USDA_fid or NFP_id is no longer active
Variation: Return Cross References <xrefs>
Cross Reference Meaning
RegistryID external registry identifier
PubMedID NCBI PubMed identifier
DBURL external database home page URL
TaxonomyID NCBI taxonomy identifier
SourceName external depositor name
SourceCategory depositor category(ies)

Quality Control using Provenance Ontology and REST

Several conversation € types will be supported.

For example, Ontomatica imports € the Provenance Ontology [prov].

The following illustrates a curator € using [prov]:

  • Alanna wishes to verify that a new data set correctly addresses previous error.
  • David [ex:David] documents Alanna’s instructions [ex:instructions] in a plan [prov:Plan].
  • David then generates a new dataset [ex:dataset2] that implements correction activity [ex:correct1].
  • Alanna confirms [prov:Plan] and executes a diff (difference) to contrast [ex:dataset2] with [ex:dataset1].

Curator uses a REST conversation to implement the example above.

See also

Model sites that implement REST

Return to top