S3DB
 
Search this site

Recent site activity

  • S3QLStructure
    edited by Lena Deus
    attachment from Lena Deus
    attachment removed by Lena Deus
  • S3QLSyntax
    attachment from Lena Deus
    attachment removed by Lena Deus
  • lixo
    edited by Jonas Almeida
  • Core
    attachment from Jonas Almeida
    edited by Jonas Almeida
  • core
    created by Jonas Almeida
  • View All
Documentation‎ > ‎

API functions


Contents

  1. 1 Basic functions S3QL.php and URI.php
  2. 2 Serialize SPARQL to S3QL
  3. 3 Visualizing the Ontology (using Touchgraph)
  4. 4 Exporing in XML
  5. 5 Export/Import in RDF
  6. 6 Using Username and Password in the API
  7. 7 Creating a Dictionary
  8. 8 Uploading files to S3DB over HTTP
  9. 9 Downloading Files Stored in S3DB
  10. 10 Encrypt Strings
  11. 11 Decrypt Strings


Basic functions S3QL.php and URI.php

S3QL.php

URI: http://mys3dblocaldeployment/S3QL.php

Arguments:
key
query
format (see api export formats for possible values)

Example
http://mys3dblocaldeployment/S3QL.php?key=xxxxxx&format=rdf&query=<S3QL><select>*</select><from>collections</from><where><project_id>126</project_id></where></S3QL>


URI.php

URI: http://mys3dblocaldeployment/URI.php

Arguments:
key
uid
format (see api export formats for possible values)

Example
http://mys3dblocaldeployment/URI.php?key=xxxxxx&format=rdf&uid=P126

Serialize SPARQL to S3QL



sparql.php

URI: http://mys3dblocaldeployment/sparql.php

Arguments (mandatory):
query - A query, formatted as SPARQL. If there are no user defined Prefixes and you wish to query the local deployment, you may leave out the "Prefix", the "Select" and the "From" portions of the query

Arguments (optional)
key

format (see api export formats for possible values; also, for this function only you may export using the 'sparql-xml' formalist)

filename - Boolean: select 1 if you want to retrieve only a link for the file with the RDF resulting from gathering data from S3QL; select 0 (default) if you wish to use S3DB internal SPARQL engine to resolve the query with relational algebra

clean - Boolean: select 1 if you wish the query to be run on previously collected RDF (usefull for deployments where the datasets are fixed); select 0 (default) if you wish the data to be collected at the time when the query is performed

Example
http://mys3dblocaldeployment/sparql.php?key=xxxxxx&query=?A :R429 ?B .

NOTE: If you are using this service from another application, you may need to urlencode the query (replace spaces and other non-standard characters with the URL encoding equivalent - http://www.blooberry.com/indexdot/html/topics/urlencoding.htm

Visualizing the Ontology (using Touchgraph)

A call can be made immediately on the API script which builds the map of the ontology: mapproject.php

mapproject.php

URI: http://mys3dblocaldeployment/mapproject.php
Arguments (mandatory):
key
project_id


Exporing in XML

You can export a project schema (it's rules) in XML. For this, use the function: xmlproject.php

xmlproject.php

URI: http://mys3dbdeployment/s3db/xmlproject.php
Arguments (mandatory):
key
project_id
Arguments (optional):
link - save the document as a URI (default prompts for download and saving the RDF document)


Export/Import in RDF

To export a project that is hosted in a deployment of S3DB into RDF, simply call the API function built for that purpose: rdf.php

rdfexport.php

(Please note: This function used to be called rdf.php)

URI: http://mys3dbdeployment/s3db/rdfexport.php
Arguments (mandatory):
key
project_id
file (the path where the output file will be saved)
Arguments (optional):
all - export both schema and data (default exports just the schema)
permissions - export the permission level of users/groups in resources
nocore - do not export core elements (please note a file exported in this manner may be SPARQLed, but may NOT be re-imported)
format - translate the output document in format
    - rdf
    - json
    - turtle
    - n3 (default)

link - save the document as a URI (default prompts for download and saving the RDF document)
files -Either 0 or 1 to instruct rdfexport.php not to export complete files, but links to the files

Note: It is possible to run rdfexport.php on the command line. In cases when the projects are large, when attempting to download RDF through the interface, you might run into the awful "HTTP Request Failed!" message.

To run it on the command line, you need to use your shell to enter the directory where you have installed s3db. An additional parameter, "file" may be used to control where the output file will be stored:

php -f rdfexport.php key=xxxxx project_id=126 all=1 file=/home/mhdeus/theNameOfTheOutputFile.n3 format=turtle

To re-import the project in another deployment of S3DB, use the function: redRestore.php

rdfRestore.php

URI: http://mys3dbdeployment/s3db/rdfRestore.php
Arguments (mandatory):
key
file - the RDF/N3 file you intend to restore
Arguments (optional):
load - import data from the rdf file without replicating UID (every UID will be re-created)

If using the command line, please use the following syntax:

php -f rdfRestore.php key=xxx file=/home/mhdeus/myFile.n3 load=1



Using Username and Password in the API

You can use your regular Username and Password via the API. This will have the effect of creating a temporary key, which can then be used to query the data: apilogin.php

apilogin.php

URI: http://mys3dbdeployment/s3db/apilogin.php
Arguments (mandatory):
username
password
Arguments (optional):
authority => by default, accepted authentication authorities are S3DB and Google, but you may add new ones in the 'user management' project. These must comply to either, ldap, ftp or http protocols.

Output:
An html table with a key

Example: http://mys3dbdeployment/s3db/apilogin.php?username=dummy&password=dumpass&authority=mdanderson


Creating a Dictionary

You may create association between s3db URI and other external UID by adding "links". These must be created with a namespace that already exists in the s3dbDictionary (See also Dictionary in S3QL syntax).


dictionary.php

URI: http://mys3dbdeployment/s3db/dictionary.php
Arguments (mandatory):
key
query (formatted as in S3QL.php)

Output:
An html table with the result of the query

Example: 
http://mys3dbdeployment/s3db/dictionary.php?query=<S3QL><insert>namespace</insert><where><qname>mged</qname><URL>http://mged.sourceforge.net/ontologies/MGEDOntology.1.3.0.1.owl</URL></where></S3QL>


http://mys3dbdeployment/s3db/dictionary.php?key=xxxx&query=<S3QL><insert>link</insert><where><uid>I11206</uid><relation>rdfs:seeAlso</relation><value>mged:array</value></where></S3QL>

http://mys3dbdeployment/s3db/dictionary.php?key=xxxx&query=<S3QL><select>*</select><from>namespaces</from></S3QL>

http://mys3dbdeployment/s3db/dictionary.php?key=xxxx&query=<S3QL><select>*</select><from>links</from></S3QL>




Uploading files to S3DB over HTTP


You can upload files to s3db without the need to have an account on an FTP server. Simply using your key, you can upload the files to S3DB by packets upon encoding them with base 64. Here is an example of how it works:

1. Let S3DB know that a file is coming by calling uploads.php:
Provide uploads.php with a valid S3DB key and a filename (if provided, filesize will also be used). Both parameters are provided to "uploads.php" using the GET method.
Ex: http://localhost/s3db/uploads.php?key=Y1F2mHOgGSdJjqC&filename=airplane.gif&filesize=9747



2. Send the fragments of the file to S3DB
Use the filekey to upload the fragments, indicating in each case the order of the fragment being uploaded and the total number of fragments.
If the fragments were encoded individually use encode=2 (encode=1 or empty encode expect the entire file to have been encoded at once)
Ex: http://localhost/s3db/uploads.php?filekey=RXvYe0xzWoKr&fragNr=1/4&encode=1
&fileStr=d2VyZSB5b3Ugc21hcnQgZW5vdWdoIHRvIGRlY29kZSB0aGlzIHN0cmluZyBhbmQgc2VlIHdoYXQgaXQgc2F5cz8gOy0pIA==

Note: The variables filekey, fragNr, encode and fileStr can also be sent using a POST instead of a GET

Downloading Files Stored in S3DB


You can download a file stored in S3DB through the API using the function download.php
 Keep in mind that all files are stored as statements, therefore you will need a statement_id in order to retrieve a file

download.php

URI: http://mys3dbdeployment/s3db/download.php
Arguments (mandatory):
statement_id - The statement_id where the file has been saved
key - The user key to access S3DB

Arguments (optional)
download - Boolean , specify whether the file content should be displayed on the screen (0) or pushed into the HTTP header (1)

datatype - When format is JSON, you may choose if you want the contents to be encapsulated between quotes by specifying datatype=string. Alternative alguments are "var" (does not urlencode the content) and "numeric" (does not urlencode the content; adds "[" to the beggining and "]" to the end of the file content)

Output:
The file

Example: 
http://mys3dbdeployment/s3db/download.php?statement_id=12345&key=XXXXX

Encrypt Strings

encrypt.php

URI: http://mys3dbdeployment/s3db/encrypt.php
Arguments (mandatory):
q - The string to be encrypted

Arguments (optional)
public_key - You may choose to specify your own public_key; data needs to be decripted with the private_key corresponding to the public_key that you specify

Output:
The encrypted string

Example: 
http://mys3dbdeployment/s3db/encrypt.php?q=hidemypassword&public_key=XXXXX

Decrypt Strings


String and queries can be decrypted using a private key, provided by the user, or a private key stored in an S3DB project to which the user has access (use getRSAKeys.php with argument 'action=save' to create and save a publickey/privatekey pair.

decrypt.php

URI: http://mys3dbdeployment/s3db/decrypt.php

Arguments (mandatory):
crypt - An s3db key that grants access to the private key

string - The string to be decrypted; this argument can be replace by 'query', corresponding to a query, in the S3QL syntax, that returns encrypted data


Arguments (optional)
query - A query, in the S3QL syntax, that returns encrypted data to be decrypted

key - The s3db key of the user with access to the data

private_key - In case you wish to specify a private_key to decrypt the data, specify it using the private_key argument


format - see API export formats

Output:
The decrypted string/query outcome

Example: 
http://mys3dbdeployment/s3db/decryptt.php?crypt=XXXXX&query=<S3QL>...</S3QL>


Generating a publicKey/privateKey pair
You can encrypt/decrypt data on S3DB using the RSA algorithm by using the function above. Since you may want to specify your own publicKey so that later you may descrypt that data using some other tool, S3DB provides a service that will generate a publicKey/privateKey pair.

getRSAKeys.php

URI: http://mys3dbdeployment/s3db/getRSAKeys.php
Arguments (mandatory):
key - The user key to access S3DB

Arguments (optional):
action - can take the values 'save' - a project will be created to store the private and public keys without exposing them; 'view' - the previously saved key is displayed

format - see API export formats

Output:
The public_key/private_key pair

Example: 
http://mys3dbdeployment/s3db/getRSAKeys.php?key=someuserkey


Attachments (1)

  • matlab_filekey.png - on Jul 30, 2008 8:27 AM by Lena Deus (version 1)
    15k View Download