Data Discovery

SlashDB is a RESTful API for relational databases, which means that you can access database records by URLs for reading and writing. Database records are abstracted as HTTP resources.

In SlashDB you can interact with individual resources, collections of resources, vectors (column) or even an individual scalar values (record field). HTTP methods (verbs) are used to interact with resources (data) referenced by URLs.

In the Data Discovery mode SlashDB forms a tree (graph actually) facade over relational databases. The hierarchy looks as follows:

  • Databases
    • Tables
      • Records
        • Fields
        • Related Records

Collection of Databases

Based on the database schema and content, SlashDB generates URLs that are natural to follow and begin with the collection of databases configured.

Resulting document contains database names and hyperlinks to further traverse to the list of tables within each database.

XML

GET http://demo.slashdb.com/db.xml

Tag names represent the names of available database resources and have href attributes with a link to those resources.

<?xml version='1.0' encoding='utf-8'?>
<SlashDB xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns="http://www.vtenterprise.com/slashdb"
 xsi:schemaLocation="http://www.vtenterprise.com/slashdb http://demo.slashdb.com/db.xsd">

 <Pubs href="http://demo.slashdb.com/db/Pubs.xml"/>
 <Chinook href="http://demo.slashdb.com/db/Chinook.xml"/>
 <Northwind href="http://demo.slashdb.com/db/Northwind.xml"/>
</SlashDB>

JSON

GET http://demo.slashdb.com/db.json

A dictionary object is returned where keys represent database resource names and values contain links to those resources. A special “__href” key contains the address to this resource.

{
    "Pubs": "http://demo.slashdb.com/db/Pubs.json",
    "Chinook": "http://demo.slashdb.com/db/Chinook.json",
    "Northwind": "http://demo.slashdb.com/db/Northwind.json",
    "__href": "http://demo.slashdb.com/db.json"
}

Collection of Tables

To get a list of tables in a database “follow” one of the links obtained from the collection of databases document. We will use the Chinook database for all examples here. As before, all data formats are available but for the sake of brevity we will generally discuss XML and JSON only.

XML

GET http://demo.slashdb.com/db/Chinook.xml

Tags names correspond to the names of database tables and have a href attribute with a link to those resources, which are collection of records.

<?xml version='1.0' encoding='utf-8'?>
<SlashDB xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.vtenterprise.com/slashdb"
         xsi:schemaLocation="http://www.vtenterprise.com/slashdb http://demo.slashdb.com/db/Chinook.xsd">
  <Chinook href="http://demo.slashdb.com/db/Chinook.xml">
    <Album href="http://demo.slashdb.com/db/Chinook/Album.xml"/>
    <Artist href="http://demo.slashdb.com/db/Chinook/Artist.xml"/>
    <Customer href="http://demo.slashdb.com/db/Chinook/Customer.xml"/>
    <Employee href="http://demo.slashdb.com/db/Chinook/Employee.xml"/>
    <Genre href="http://demo.slashdb.com/db/Chinook/Genre.xml"/>
    <Invoice href="http://demo.slashdb.com/db/Chinook/Invoice.xml"/>
    <InvoiceLine href="http://demo.slashdb.com/db/Chinook/InvoiceLine.xml"/>
    <MediaType href="http://demo.slashdb.com/db/Chinook/MediaType.xml"/>
    <Playlist href="http://demo.slashdb.com/db/Chinook/Playlist.xml"/>
    <PlaylistTrack href="http://demo.slashdb.com/db/Chinook/PlaylistTrack.xml"/>
    <Track href="http://demo.slashdb.com/db/Chinook/Track.xml"/>
  </Chinook>
</SlashDB>

JSON

GET http://demo.slashdb.com/db/Chinook.json

{
    "Chinook": {
        "Album": "http://demo.slashdb.com/db/Chinook/Album.json",
        "Customer": "http://demo.slashdb.com/db/Chinook/Customer.json",
        "Playlist": "http://demo.slashdb.com/db/Chinook/Playlist.json",
        "Artist": "http://demo.slashdb.com/db/Chinook/Artist.json",
        "Track": "http://demo.slashdb.com/db/Chinook/Track.json",
        "__href": "http://demo.slashdb.com/db/Chinook.json",
        "MediaType": "http://demo.slashdb.com/db/Chinook/MediaType.json",
        "Genre": "http://demo.slashdb.com/db/Chinook/Genre.json",
        "Invoice": "http://demo.slashdb.com/db/Chinook/Invoice.json",
        "InvoiceLine": "http://demo.slashdb.com/db/Chinook/InvoiceLine.json",
        "Employee": "http://demo.slashdb.com/db/Chinook/Employee.json",
        "PlaylistTrack": "http://demo.slashdb.com/db/Chinook/PlaylistTrack.json"
    }
}

Records

GET http://demo.slashdb.com/db/Chinook/Customer.xml?limit=3

A collection of records from Customer table is returned. Note the “limit” URL modifier, which we used to return only 3 records for brevity (see below for more on URL modifiers).


<?xml version="1.0" encoding="utf-8"?>
<SlashDB xmlns="http://www.vtenterprise.com/slashdb" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:schemaLocation="http://www.vtenterprise.com/slashdb http://demo.slashdb.com/db/Chinook/Customer.xsd">
  <Customer href="http://demo.slashdb.com/db/Chinook/Customer/CustomerId/1.xml">
    <CustomerId>1</CustomerId>
    <Invoice href="http://demo.slashdb.com/db/Chinook/Invoice/CustomerId/1.xml"/>
    <FirstName>Luís</FirstName>
    <LastName>Gonçalves</LastName>
    <Company>Embraer - Empresa Brasileira de Aeronáutica S.A.</Company>
    <Address>Av. Brigadeiro Faria Lima, 2170</Address>
    <City>São José dos Campos</City>
    <State>SP</State>
    <Country>Brazil</Country>
    <PostalCode>12227-000</PostalCode>
    <Phone>+55 (12) 3923-5555</Phone>
    <Fax>+55 (12) 3923-5566</Fax>
    <Email>luisg@embraer.com.br</Email>
    <SupportRepId>3</SupportRepId>
    <Employee href="http://demo.slashdb.com/db/Chinook/Employee/EmployeeId/3.xml"/>
  </Customer>
  <Customer href="http://demo.slashdb.com/db/Chinook/Customer/CustomerId/2.xml">
    <CustomerId>2</CustomerId>
    <Invoice href="http://demo.slashdb.com/db/Chinook/Invoice/CustomerId/2.xml"/>
    <FirstName>Leonie</FirstName>
    <LastName>Köhler</LastName>
    <Address>Theodor-Heuss-Straße 34</Address>
    <City>Stuttgart</City>
    <Country>Germany</Country>
    <PostalCode>70174</PostalCode>
    <Phone>+49 0711 2842222</Phone>
    <Email>leonekohler@surfeu.de</Email>
    <SupportRepId>5</SupportRepId>
    <Employee href="http://demo.slashdb.com/db/Chinook/Employee/EmployeeId/5.xml"/>
  </Customer>
  <Customer href="http://demo.slashdb.com/db/Chinook/Customer/CustomerId/3.xml">
    <CustomerId>3</CustomerId>
    <Invoice href="http://demo.slashdb.com/db/Chinook/Invoice/CustomerId/3.xml"/>
    <FirstName>François</FirstName>
    <LastName>Tremblay</LastName>
    <Address>1498 rue Bélanger</Address>
    <City>Montréal</City>
    <State>QC</State>
    <Country>Canada</Country>
    <PostalCode>H2G 1A7</PostalCode>
    <Phone>+1 (514) 721-4711</Phone>
    <Email>ftremblay@gmail.com</Email>
    <SupportRepId>3</SupportRepId>
    <Employee href="http://demo.slashdb.com/db/Chinook/Employee/EmployeeId/3.xml"/>
  </Customer>
</SlashDB>

An individual record resource is data of a single row in a table (if not following relations) represented in XML (XML Schema also available), JSON, CSV (2 dimensional table) or simply an HTML for viewing purposes.

Example of individual record:

CustomerID 10 from table Customer in

http://demo.slashdb.com/db/Chinook/Customer/CustomerId/10.xml

Example #: http://demo.slashdb.com/db/Chinook/Customer.xml –  all customers

Record Filtering

It’s possible to narrow results using filters. Simply after name of database add pairs of column name and filtering value separated by “/” like Column1/Value1/Column2/Value2

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA.xml – customers from USA

Example #:  http://demo.slashdb.com/db/Chinook/Customer/Country/USA/State/CA/City/Mountain%20View.xml – customers from Mountain View, California, USA

You’ll receive a one resource when filtering by a primary key or if the filtering narrows to a single resource

Example #1:  http://demo.slashdb.com/db/Chinook/Customer/CustomerId/1.html

Example #2: http://demo.slashdb.com/db/Chinook/Customer/FirstName/Lu%C3%ADs/LastName/Gon%C3%A7alves.html

Additional parameters

limit = [int]

Limits the number of results.

Default is no limit.

Example #: http://demo.slashdb.com/db/Chinook/Customer.xml?limit=5 – 5 customers

offset = [int]

Omits the number of results.

Default is 0.

Example #: http://demo.slashdb.com/db/Chinook/Customer.xml?offset=1 – omits 1st customer

depth = [int]

Returns resources with all related resources. The number indicates how many subsequent relations must be included (nested) in result. It’s to be used with common sense as to high depth may easily return large amount of data.

Default is 0 – no offset

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/Canada.xml?depth=1

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/Canada.json?depth=2

cardinality = [1, n]

XML Schema only.

Sets xsd:element maxOccurs parameter

Default is n which corresponds with maxOccurs=’unbounded’

Scalars and Vectors (html, xml, xsd, json, csv, txt)

Scalar is an attribute of a resource – a column for a certain row.  URLs for scalars have an additional segment (columns name) after resource query.

Example #: http://demo.slashdb.com/db/Chinook/Customer/CustomerId/15/Address.xml – an address of a certain customer

A vector of values is returned if filtering returns more than one resource

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA/State/CA/Address.xml – addresses of customers from California, USA.

Filtering

See resources filtering.

Additional parameters

Those parameters are added at the end or URL after extension, starting with question mark ? and separating multiple parameters with ampersand &.

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA/Address.xml?limit=5&offset=2&sort&distinct

limit = [int]

Limits the number of scalars.

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA/Address.xml?limit=5 – just first 5 customers

offset = [int]

Omits the number of scalars.

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA/Address.xml?offset=3 – skip first 3 customers

sort

Sorts a vector.

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA/State.xml?sort – Customers’ states sorted

distinct

Removes duplicates from a vector.

Example #: http://demo.slashdb.com/db/Chinook/Customer/Country/USA/State.xml?distinct – distinct

PUT – update data in a database

When updating an existing resource you may send all information about resource

{
    "InvoiceId": 666,
    "BillingPostalCode": "666666",
    "InvoiceDate": "2007-01-01T00:00:00",
    "BillingAddress": "Theodor-Heuss-Stra\u00dfe 34",
    "BillingCountry": "Germany",
    "Total": 1.98,
    "CustomerId": 2,
    "BillingCity": "Stuttgart"
}

or just information you want to update

{
    "BillingAddress": "Theodor-Heuss-Stra\u00dfe 34",
    "Total": 1.98,
    "CustomerId": 2,
    "BillingCity": "Stuttgart"
}
Updating single resource using JSON
{
    "InvoiceId": 666,
    "BillingPostalCode": "666666",
    "InvoiceDate": "2007-01-01T00:00:00",
    "BillingAddress": "Theodor-Heuss-Stra\u00dfe 34",
    "BillingCountry": "Germany",
    "Total": 1.98,
    "CustomerId": 2,
    "BillingCity": "Stuttgart"
}

Pass JSON in PUT request to the SlashDB server:

curl -H 'Content-type: application/json' -X PUT -d@invoice.json http://demo.slashdb.com/db/Chinook/Invoice.json
Updating single resource using XML
<?xml version='1.0' encoding='utf-8'?>
<SlashDB xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns="http://www.vtenterprise.com/slashdb">
  <Invoice>
    <InvoiceId>666</InvoiceId>
    <CustomerId>2</CustomerId>
    <InvoiceDate>2007-01-01T00:00:00</InvoiceDate>
    <BillingAddress>Theodor-Heuss-Straße 34</BillingAddress>
    <BillingCity>Stuttgart</BillingCity>
    <BillingCountry>Germany</BillingCountry>
    <BillingPostalCode>70174</BillingPostalCode>
    <Total>1.98</Total>
  </Invoice>
</SlashDB>

Pass XML in POST request to the SlashDB server:

curl -H 'Content-type: text/xml' -X PUT -d@invoice.xml http://demo.slashdb.com/db/Chinook/Invoice.xml
Posting single resource in CSV
InvoiceId,CustomerId,InvoiceDate,BillingAddress,BillingCity,BillingState,BillingCountry,BillingPostalCode,Total
666,2,2007-01-01 00:00:00,Theodor-Heuss-Straße 34,Stuttgart,,Germany,70174,1.98

Pass json in post request to the http server:

curl -H 'Content-type: text/csv' -X POST -d@invoice.csv http://demo.slashdb.com/db/Chinook/Invoice.csv
Posting many resources in one JSON
 [
    {
        "InvoiceId": 661,
        "BillingPostalCode": "70174",
        "InvoiceDate": "2007-01-01T00:00:00",
        "BillingAddress": "Theodor-Heuss-Stra\u00dfe 34",
        "BillingCountry": "FooLand",
        "Total": 1.98,
        "CustomerId": 2,
        "BillingCity": "Stuttgart"
    },
    {
        "InvoiceId": 662,
        "BillingPostalCode": "60316",
        "InvoiceDate": "2007-01-19T00:00:00",
        "BillingAddress": "Berger Stra\u00dfe 10",
        "BillingCountry": "FooLand",
        "Total": 0.99,
        "CustomerId": 37,
        "BillingCity": "Frankfurt"
    },
    {
        "InvoiceId": 663,
        "BillingPostalCode": "10779",
        "InvoiceDate": "2007-02-01T00:00:00",
        "BillingAddress": "Barbarossastra\u00dfe 19",
        "BillingCountry": "FooLand",
        "Total": 1.98,
        "CustomerId": 38,
        "BillingCity": "Berlin"
    }
]
Posting many resources in one XML
<SlashDB xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns="http://www.vtenterprise.com/slashdb">
  <Invoice>
    <InvoiceId>661</InvoiceId>
    <CustomerId>2</CustomerId>
    <InvoiceDate>2007-01-01T00:00:00</InvoiceDate>
    <BillingAddress>Theodor-Heuss-Straße 34</BillingAddress>
    <BillingCity>Stuttgart</BillingCity>
    <BillingCountry>FooLand</BillingCountry>
    <BillingPostalCode>70174</BillingPostalCode>
    <Total>1.98</Total>
  </Invoice>
  <Invoice>
    <InvoiceId>662</InvoiceId>
    <CustomerId>37</CustomerId>
    <InvoiceDate>2007-01-19T00:00:00</InvoiceDate>
    <BillingAddress>Berger Straße 10</BillingAddress>
    <BillingCity>Frankfurt</BillingCity>
    <BillingCountry>FooLand</BillingCountry>
    <BillingPostalCode>60316</BillingPostalCode>
    <Total>0.99</Total>
  </Invoice>
  <Invoice>
    <InvoiceId>663</InvoiceId>
    <CustomerId>38</CustomerId>
    <InvoiceDate>2007-02-01T00:00:00</InvoiceDate>
    <BillingAddress>Barbarossastraße 19</BillingAddress>
    <BillingCity>Berlin</BillingCity>
    <BillingCountry>FooLand</BillingCountry>
    <BillingPostalCode>10779</BillingPostalCode>
    <Total>1.98</Total>
  </Invoice>
</SlashDB>
Posting many resources in one CSV
InvoiceId,CustomerId,InvoiceDate,BillingAddress,BillingCity,BillingState,BillingCountry,BillingPostalCode,Total
661,2,2007-01-01 00:00:00,Theodor-Heuss-Straße 34,Stuttgart,,FooLand,70174,1.98
662,37,2007-01-19 00:00:00,Berger Straße 10,Frankfurt,,FooLand,60316,0.99
663,38,2007-02-01 00:00:00,Barbarossastraße 19,Berlin,,FooLand,10779,1.98

Scalars

POST – upload data to a database

Posting single resource in JSON
{
    "InvoiceId": 666,
    "BillingPostalCode": "666666",
    "InvoiceDate": "2007-01-01T00:00:00",
    "BillingAddress": "Theodor-Heuss-Stra\u00dfe 34",
    "BillingCountry": "Germany",
    "Total": 1.98,
    "CustomerId": 2,
    "BillingCity": "Stuttgart"
}

Pass json in post request to the http server:

curl -H 'Content-type: application/json' -X POST -d@invoice.json http://demo.slashdb.com/db/Chinook/Invoice.json
Posting single resource in XML
<?xml version='1.0' encoding='utf-8'?>
<SlashDB xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns="http://www.vtenterprise.com/slashdb">
  <Invoice>
    <InvoiceId>666</InvoiceId>
    <CustomerId>2</CustomerId>
    <InvoiceDate>2007-01-01T00:00:00</InvoiceDate>
    <BillingAddress>Theodor-Heuss-Straße 34</BillingAddress>
    <BillingCity>Stuttgart</BillingCity>
    <BillingCountry>Germany</BillingCountry>
    <BillingPostalCode>70174</BillingPostalCode>
    <Total>1.98</Total>
  </Invoice>
</SlashDB>

Pass json in post request to the http server:

curl -H 'Content-type: text/xml' -X POST -d@invoice.xml http://demo.slashdb.com/db/Chinook/Invoice.xml
Posting single resource in CSV
InvoiceId,CustomerId,InvoiceDate,BillingAddress,BillingCity,BillingState,BillingCountry,BillingPostalCode,Total
666,2,2007-01-01 00:00:00,Theodor-Heuss-Straße 34,Stuttgart,,Germany,70174,1.98

Pass json in post request to the http server:

curl -H 'Content-type: text/csv' -X POST -d@invoice.csv http://demo.slashdb.com/db/Chinook/Invoice.csv
Posting many resources in one JSON
 [
    {
        "InvoiceId": 661,
        "BillingPostalCode": "70174",
        "InvoiceDate": "2007-01-01T00:00:00",
        "BillingAddress": "Theodor-Heuss-Stra\u00dfe 34",
        "BillingCountry": "FooLand",
        "Total": 1.98,
        "CustomerId": 2,
        "BillingCity": "Stuttgart"
    },
    {
        "InvoiceId": 662,
        "BillingPostalCode": "60316",
        "InvoiceDate": "2007-01-19T00:00:00",
        "BillingAddress": "Berger Stra\u00dfe 10",
        "BillingCountry": "FooLand",
        "Total": 0.99,
        "CustomerId": 37,
        "BillingCity": "Frankfurt"
    },
    {
        "InvoiceId": 663,
        "BillingPostalCode": "10779",
        "InvoiceDate": "2007-02-01T00:00:00",
        "BillingAddress": "Barbarossastra\u00dfe 19",
        "BillingCountry": "FooLand",
        "Total": 1.98,
        "CustomerId": 38,
        "BillingCity": "Berlin"
    }
]
Posting many resources in one XML
<SlashDB xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns="http://www.vtenterprise.com/slashdb">
  <Invoice>
    <InvoiceId>661</InvoiceId>
    <CustomerId>2</CustomerId>
    <InvoiceDate>2007-01-01T00:00:00</InvoiceDate>
    <BillingAddress>Theodor-Heuss-Straße 34</BillingAddress>
    <BillingCity>Stuttgart</BillingCity>
    <BillingCountry>FooLand</BillingCountry>
    <BillingPostalCode>70174</BillingPostalCode>
    <Total>1.98</Total>
  </Invoice>
  <Invoice>
    <InvoiceId>662</InvoiceId>
    <CustomerId>37</CustomerId>
    <InvoiceDate>2007-01-19T00:00:00</InvoiceDate>
    <BillingAddress>Berger Straße 10</BillingAddress>
    <BillingCity>Frankfurt</BillingCity>
    <BillingCountry>FooLand</BillingCountry>
    <BillingPostalCode>60316</BillingPostalCode>
    <Total>0.99</Total>
  </Invoice>
  <Invoice>
    <InvoiceId>663</InvoiceId>
    <CustomerId>38</CustomerId>
    <InvoiceDate>2007-02-01T00:00:00</InvoiceDate>
    <BillingAddress>Barbarossastraße 19</BillingAddress>
    <BillingCity>Berlin</BillingCity>
    <BillingCountry>FooLand</BillingCountry>
    <BillingPostalCode>10779</BillingPostalCode>
    <Total>1.98</Total>
  </Invoice>
</SlashDB>
Posting many resources in one CSV
InvoiceId,CustomerId,InvoiceDate,BillingAddress,BillingCity,BillingState,BillingCountry,BillingPostalCode,Total
661,2,2007-01-01 00:00:00,Theodor-Heuss-Straße 34,Stuttgart,,FooLand,70174,1.98
662,37,2007-01-19 00:00:00,Berger Straße 10,Frankfurt,,FooLand,60316,0.99
663,38,2007-02-01 00:00:00,Barbarossastraße 19,Berlin,,FooLand,10779,1.98

Document Types

Each URL has to end with format in which data must be returned. SlashDB support:

  • .xml – Extensible Markup Language
  • .xsd – Schema for XML
  • .json – JavaScript Object Notation
  • .csv – comma separated values
  • .html – browsable websites (generally for viewing purposes)

SQL Pass-thru

SlashDB with SQL Pass-thru allows you to save your SQL query for execution in the future.  Again SlashDB provides you with separate URLs for each query you’ve saved.

Error Messages