| The REST API |
|
The preferred, or primary, XBRL Cloud Web Services API is this REST API.
- Session Methods
-
Yes, we know session data isn't RESTful. Please read details below.
- Validation & Debugging Methods
-
- Standard Report Methods
-
- Transformation Methods
-
- XBRL Cloud User Files
-
Regardless of what services you call, you will need the same login credentials that you use everywhere else in the system.
You may wish to consider:
|
|
Session Method: Login
|
|
Purpose
The login method establishes a user session. Sessions are not RESTful. However, as
you are probably aware, XBRL is extremely memory and CPU
intensive. The session is only used to "cache" the XBRL in
memory. Specifically, the cache is relevant to an XBRL "entry
point", such as an instance document. When the entry point
changes, the cache is reset.
You do not need to call the login method: Accessing any other
method (besides logout) will automatically log you in via the
authentication.
The login method is only for convenience. Notably, when in a
browser, the user is placed in their home directory.
Route
http://user.xbrlcloud.com/rest/login
Method Details
None
Example Usage
http://guest.xbrlcloud.com/rest/login
|
|
Session Method: Logout
|
|
Purpose
The logout method ends a user session. Specifically, any cache
associated with the user is released, thereby freeing up server
resources. While we request that you log out the user, the
session will terminate (the cache will be unloaded) after ten
minutes of inactivity.
We respectfully ask that you (or your application) logout when reasonable to free up system resources.
Route
http://user.xbrlcloud.com/rest/logout
Method Details
None
Example Usage
http://guest.xbrlcloud.com/rest/logout
|
|
Validation: XBRL Validation
|
|
Purpose
Validate an XBRL document. Validation might be as simple as basic XBRL 2.1 validation, or as complex as EDGAR validation.
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/validation/xbrl?flavor={flavor-value}&media={media-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
flavor
|
Not required: defaults to standard
|
Type of validation. Each flavor indicates a different set of rules to check. In all cases, the flavors include standard validation.
|
standard
|
Standard XBRL 2.1 Validation. per the XBRL 2.1 Specification.
|
|
|
|
frta
|
This is standard XBRL 2.1 validation plus validation rules specified by FRTA.
|
|
|
|
sec_informal_criteria
|
This is standard XBRL 2.1 validation plus validation
rules specified by
the SEC Public Validation Criteria.
|
|
|
|
edgar_v10
|
This is standard XBRL 2.1 validation plus validation
rules specified by
the SEC's
EDGAR Filer Manual.
|
|
|
|
xbrls
|
This is standard XBRL 2.1 validation plus validation rules specified by The XBRL Simple Profile.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
XBRL 2.1 validation on an instance document — XHTML result
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-ComprehensiveExample-2008-04-18;gaap;Sample-Instance-Proof.xml/validation/xbrl?media=xhtml
EDGAR validation on an instance document — XML result
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-ComprehensiveExample-2008-04-18;gaap;Sample-Instance-Proof.xml/validation/xbrl?flavor=EDGAR_V10&media=xml
|
|
Debugging: Hypercube Trace
|
|
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/validation/hypercube-trace?media={media-value}&camel-case={boolean-value}
Purpose
Dump a detailed trace of hypercube validation. This report is extremely useful for debugging XBRL instances.
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xls
|
Request an application/excel document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
Hypercube Trace — Excel result:
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-ComprehensiveExample-2008-04-18;gaap;Sample-Instance-Proof.xml/validation/hypercube-trace?media=xls
|
|
Standard Report: Report Summary
|
|
Purpose
Get a list of all other available reports. This method is mostly used in the browser.
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/reports?media={media-value}&camel-case={boolean-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-MetaPatterns-2008-04-18;2008-04-18;99-Combined;gaap-SampleInstance.xml/reports
|
|
Standard Report: Concepts & Labels
|
|
Purpose
Get a list of all of the concepts, and the corresponding labels.
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/concepts?media={media-value}&camel-case={boolean-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-MetaPatterns-2008-04-18;2008-04-18;99-Combined;gaap-SampleInstance.xml/concepts
|
|
Standard Report: Tree Instance & Taxonomy View
|
|
Purpose
Display concepts and facts. There are several embedded views,
notably for driven by the presentation and calculation networks.
The report is a basically "tree" list that maps nicely to Excel (for
example). That said, it's an okay—but not great—way to
look at instance data.
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/networks/tree-view?media={media-value}&camel-case={boolean-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
|
|
xls
|
Request an application/excel document.
|
|
param-show-presentation
|
Not required: defaults to true.
|
Determine whether or not to show the presentation tree.
|
true
|
Show the presentation tree.
|
|
|
|
false
|
Omit the presentation tree.
|
|
param-show-calculation
|
Not required: defaults to true.
|
Determine whether or not to show the calculation tree.
|
true
|
Show the calculation tree.
|
|
|
|
false
|
Omit the calculation tree.
|
|
param-show-hypercubes
|
Not required: defaults to true.
|
Determine whether or not to show the hypercubes tree.
|
true
|
Show the hypercubes tree.
|
|
|
|
false
|
Omit the hypercubes tree.
|
|
param-show-hypercubes-in-presentation
|
Not required: defaults to false.
|
For each concept in the presentation tree, list hypercubes associated with that concept in the same extended link role URI.
|
true
|
Show related hypercubes.
|
|
|
|
false
|
Omit the presentation tree.
|
|
param-show-facts
|
Not required: defaults to true.
|
Determine whether or not to show facts associated with each concept
|
true
|
Show the facts.
|
|
|
|
false
|
Omit the facts.
|
|
param-show-orphaned-concepts
|
Not required: defaults to false.
|
Determine whether or not to show the orphaned concepts. An orphaned concept is one that does not appear in any presentation, calculation, or hypercube
|
true
|
Show the orphaned concepts.
|
|
|
|
false
|
Omit the orphaned concepts.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-MetaPatterns-2008-04-18;2008-04-18;99-Combined;gaap-SampleInstance.xml/networks/tree-view?media=xls
|
|
Standard Report: Grid Instance & Taxonomy View
|
|
Purpose
Display concepts and facts. There are several embedded views,
notably for driven by the presentation and calculation networks.
The report is a basically "grid" list that maps nicely to Excel (for
example). That said, it's an okay—but not great—way to
look at instance data.
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/networks/grid-view?media={media-value}&camel-case={boolean-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
|
|
xls
|
Request an application/excel document.
|
|
param-show-presentation
|
Not required: defaults to true.
|
Determine whether or not to show the presentation grid.
|
true
|
Show the presentation grid.
|
|
|
|
false
|
Omit the presentation grid.
|
|
param-show-calculation
|
Not required: defaults to true.
|
Determine whether or not to show the calculation grid.
|
true
|
Show the calculation grid.
|
|
|
|
false
|
Omit the calculation grid.
|
|
param-show-hypercubes
|
Not required: defaults to true.
|
Determine whether or not to show the hypercubes grid.
|
true
|
Show the hypercubes grid.
|
|
|
|
false
|
Omit the hypercubes grid.
|
|
param-show-hypercubes-in-presentation
|
Not required: defaults to false.
|
For each concept in the presentation grid, list hypercubes associated with that concept in the same extended link role URI.
|
true
|
Show related hypercubes.
|
|
|
|
false
|
Omit the presentation grid.
|
|
param-show-facts
|
Not required: defaults to true.
|
Determine whether or not to show facts associated with each concept
|
true
|
Show the facts.
|
|
|
|
false
|
Omit the facts.
|
|
param-show-orphaned-concepts
|
Not required: defaults to false.
|
Determine whether or not to show the orphaned concepts. An orphaned concept is one that does not appear in any presentation, calculation, or hypercube
|
true
|
Show the orphaned concepts.
|
|
|
|
false
|
Omit the orphaned concepts.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-MetaPatterns-2008-04-18;2008-04-18;99-Combined;gaap-SampleInstance.xml/networks/grid-view?media=xls
|
|
Standard Report: Data Cubes
|
|
Purpose
Get data in an OLAP type format. Notably, once this is put into Excel, the user can create their own pivot tables.
Route
http://user.xbrlcloud.com/rest/xbrl/{document-url}/olap/cubes?media={media-value}&camel-case={boolean-value}&flashify={boolean-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
json
|
Request an application/json document.
|
|
|
|
xls
|
Request an application/excel document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
Transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
flashify
|
Not required: defaults to false.
|
Switches dimension elements
to dimension-qname elements.
With camel-case=true, turns:
<dimension label="Business Segment [Axis]" qname="pattern:BusinessSegmentAxis" member-label="Consolidated Group [Domain]">pattern:ConsolidatedGroupDomain</dimension>
into
<patternBusinessSegmentAxis label="Business Segment [Axis]" memberLabel="Consolidated Group [Domain]">pattern:ConsolidatedGroupDomain</patternBusinessSegmentAxis>
This option only affects results when media=xml.
While definitely not required, this option is normally used with camel-case=true.
This option was introduced specifically for FLEX applications,
which by default wants columns to have unique element names.
This option is likely valuable for other technologies as well.
|
true
|
Switch dimension elements
to dimension-qname elements.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
http://guest.xbrlcloud.com/rest/xbrl/http:;;guest.xbrlcloud.com;share;public;XBRLS-MetaPatterns-2008-04-18;2008-04-18;99-Combined;gaap-SampleInstance.xml/olap/cubes?media=xls
|
|
Transformation Method
|
|
Purpose
You can easily transform an XBRL instance and/or taxonomy into a
much more usable single document. Common applications of this
API include created XML, XHTML, or Excel output. The
transformation engine implements XPath extension functions.
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document to be validated.
|
{any URL}
|
This document likely resides on the same XBRL Cloud subdomain as the user (see example above), but can be anywhere on the internet
|
|
xsl-url
|
Required
|
An XSL stylesheet.
Please note that the XBRL Cloud transformation engine is
based on the Coyote Reporting processor: you will likely need
the
extension function documentation.
|
{any URL}
|
This document likely resides on the same XBRL Cloud subdomain as the user (see example above), but can be anywhere on the internet
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
|
|
excel
|
Request an application/excel document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
Basic XSLT Example
http://guest.xbrlcloud.com/rest/xslt?document-url=http://guest.xbrlcloud.com/share/public/...&xsl-url=http://guest.xbrlcloud.com/share/public/...
|
|
User Files
|
|
Purpose
Access user files. This method is particularly useful for:
-
Viewing "private" files (authenticated, of course).
-
Viewing a directory listing, notably in XHTML.
Route
http://user.xbrlcloud.com/path/{document-url}?media={media-value}&camel-case={boolean-value}
Method Details
|
Option
|
Required
|
Option Description
|
Value
|
Value Description
|
document-url
|
Required
|
The location of the document for which to generate the report.
|
{any URL}
|
This document likely resides on the XBRL Cloud server as well, but can be anywhere on the internet.
|
|
media
|
Not required: When not specified, media type is determined via Content Negotiation
|
The format of the return document (XML vs. XHTML vs. Excel, etc.)
|
xml
|
Request a text/xml document
|
|
|
|
xhtml
|
Request an application/xhtml document.
Note that Internet Explorer does not support application/xhtml: When the agent is IE, the server returns text/html
|
|
|
|
json
|
Request an application/json document.
|
|
camel-case
|
Not required: defaults to false.
|
Default XML tags are '-' delimited. Instead return "camel case" tags. For example, return
<fooBar>value</fooBar>
instead of
<foo-bar>value</foo-bar>
This option only affects results when media=xml.
This option was introduced specifically for FLEX applications, which sometimes get finicky when presented with tags that contain embedded '-' tags.
|
true
|
transform any tags with embedded '-' to camel case.
|
|
|
|
false
|
Return XML untouched.
|
|
Example Usage
http://guest.xbrlcloud.com/rest/path/http:;;guest.xbrlcloud.com;share
|
