Menu ▾ ▴

api

Damian Gessler

Semantic Pipeline RESTful API

Interact with the Discovery Server via RESTful interfaces

Synopsis

All URL end-points start with http://sswap.info/
/make Make SSWAP RDF/XML graphs from JSON input
/validate Validate SSWAP graphs and generic OWL 2 graphs
/reason Reason over OWL graphs
/modularize Modularize BioPoral ontologies
/publish Publish your SSWAP semantic web service to our knowledge base and be discovered
/query Discover matching services based on a service description
/search Return a web page to a new pipeline with suggested services based on the search phrase
/convert Convert between various RDF serializations
/api HTTP API for conversion of JSON specifications into SSWAP Resource Graphs and ontology types and properties


sswap.info/make
Makes SSWAP RDF/XML graphs from JSON by sending the input to the HTTP API
GET /make Retrieves a web page for user interaction
Example:
GET /make?<URL> Read the JSON file at the URL and send the contents to the HTTP API
Examples:
POST /make Read the body of the request as JSON and send the contents to the HTTP API
Example:
  • command line: curl -d@termToUpload.json http://sswap.info/make where termToUpload.json is the JSON file you are uploading to translate to RDF/XML


sswap.info/validate
Validates SSWAP graphs, such as RDGs (Resource Description Graphs), and generic OWL 2 ontologies
GET /validate Retrieves a web page for user interaction
Example:
GET /validate?<URL> Validates the graph (ontology) at the URL (e.g., an RDG Resource Description Graph)
Examples:
POST /validate Validates the graph sent as the body of the request
Example:
  • command line: curl -d@ontologyToUpload.owl http://sswap.info/validate where ontologyToUpload.owl is the file you are uploading to validate
  • Can be used for generic OWL validation
  • Validation implies reasoning; to manually reason, use /reason

  • Input format must be W3C RDF/XML OWL


sswap.info/reason
Runs an OWL 2 reasoner on the graph and returns the inferred ontology
GET /reason Retrieves a web page for user interaction
Example:
GET /reason?<URL> Reasons over the graph (ontology) at the URL (e.g., an RDG Resource Description Graph)
Examples:
POST /reason Reasons over the graph sent as the body of the request
Example:
  • command line: curl -d@ontologyToUpload.owl http://sswap.info/reason where ontologyToUpload.owl is the file you are uploading to reason
  • All RDGs are reasoned over before being published.
  • We automatically resolve terms on the web by either dereferencing them for their definitions or referring to known ontologies (Del Vescovo et al. 2011).
  • If the graph is OWL DL and if all terms can be resolved, the resulting ontology is guaranteed to be complete.
  • Input format must be W3C RDF/XML OWL


sswap.info/modularize
Modularize large BioPortal ontologies into compact necessary and sufficient entailments
GET /modularize Retrieves a web page for user interaction
Example:
GET /modularize?<term1>&<term2>&... Modularize the signature of terms
Example:
POST /modularize Body of the content must be RDF/XML statements; terms referenced therein are extracted as the signature to modularize
Example:
  • command line: curl -d@ontologyToUpload.owl http://sswap.info/modularize where ontologyToUpload.owl is the file of statements to modularize
  • A signature is a set of terms, which should be expressed by their full URLs for dereferencing. Modularization is the process of returning the minimum set of statements that still guarantee completeness over entailment for that set of terms.
  • A full solution is known to be undecidable; the algorithm uses a syntactic approximation which returns the minimal set in many conditions, but is not guaranteed minimal in all conditions.
  • Modularization may take 30 seconds or more. Internal wall clocks and byte counters are used to guarantee the return of results. In pathological cases that either take a long time to compute or require the deferencing of many dependent ontology terms, the results may not satisfy the minimal or completeness goals.
  • "Minimal" is with respect to statements with logical implications; annotation statements (e.g., rdfs:comment) may be included in the return set.


sswap.info/publish
Request a SSWAP RDG (Resource Description Graph) to be scheduled for publication
GET /publish Retrieves a web page for user interaction
Example:
POST /publish The content (body) of the POST must be either a URL or a JSON array of URLs. The URLs must dereference to a hosted SSWAP RDF/XML RDG (Resource Description Graph) such as made with the HTTP API; see /makeRDG. An RDG describes the service; to implement semantics see Hosting Semantic Web Services. Publishing is on-demand, but it may take up to four hours before the web service is discoverable.
Examples:
  • command line: curl -d http://mySite/myResource http://sswap.info/publish
  • command line: curl -d@array-of-RDG-URLs.json http://sswap.info/publish where array-of-RDG-URLs.json is a file containing a JSON array such as:
      [
        "http://mySite/myResource1",
        "http://mySite/myResource2"
      ]
  • The RDG will be validated before publication; to manually validate first, use validate
  • The RDG must be first hosted on the web (e.g., on your web server, as your semantic web service end-point) at the URL of its sswap:Resource before its is published
  • To update a published service, just republish. To remove a published service, remove or otherwise invalidate the RDG at its URL and republish the URL
  • RDGs are always W3C RDF/XML OWL


sswap.info/query
Executes a query ("find all graphs like ...") on the Discovery Server
GET /query Retrieves a web page for user interaction
Example:
GET /query?<URL> Find all services like the service at the URL
Examples:
POST /query Queries the SSWAP graph
Example:
  • command line: curl -d@resourceGaphToUpload.owl http://sswap.info/query where resourceGraphToUpload.owl is the file you are uploading to query
    (Resource graphs are one of RDG, RIG, RQG, RRG; see below)
  • Querying returns all published services that:
    • are the same or a subtype of the service in the query graph, and
    • accept an input subject that is the same or a super-type of the query graph's input subject, and
    • return an output object that is the same or a subtype of the query graph's output object
  • A query graph is called an RQG: Resource Query Graph; see /makeRQG
  • Graphs that are not RQGs are converted into an RQG automatically. Graphs must be a SSWAP RDG, RIG, RRG, or RQG; generic OWL is non-convertible. See HTTP API.
  • RDGs are easy to find: just visit sswap.info and note any discovered service's URL; that's its RDG.
  • Input format (SSWAP Resource Graphs) is W3C RDF/XML OWL
  • Output format is JSON
  • Failure to match any services returns an empty JSON array [ ]


sswap.info/search
Return a web page to a new pipeline with suggested services based on the search phrase
GET /search Retrieve the home page with a text box ready to accept a search phrase
Example:
GET /search?q= Return a web page to a new, empty pipeline
Examples:
GET /search?q=tree Return a web page to a new, empty pipeline with services that match the search phrase
Examples:


sswap.info/convert
Converts RDF graphs between formats
GET /convert Retrieves a web page for user interaction
Example:
GET /convert/xml?<URL> Converts the graph (ontology) at the URL to RDF/XML
GET /convert/n3?<URL> Converts the graph (ontology) at the URL to N3
GET /convert/nt?<URL> Converts the graph (ontology) at the URL to N-Triples
GET /convert/tsv?<URL> Converts the graph (ontology) at the URL to TSV (Tab Separated Values)
Examples:
POST /convert/{ xml | n3 | nt | tsv } Converts the graph sent as the body of the request to the requested format
Example:
  • command line: curl -d@ontologyToUpload.xml http://sswap.info/convert/n3 where ontologyToUpload.xml is the file you are uploading to convert
  • Input format is determined automatically; currently reading TSV is not supported.
  • TSV is based on the fundamental RDF truism that any RDF (subject,predicate,object) triple can be mapped to a (row,column,value) tuple. Columns correspond to properties; rows to data entries, with the first column being the subject of the properties. The TSV converter constructs a header line (first row) of unique predicates (properties) from those observed in the graph. Subsequent rows correspond to at least one row per subject, with cells either filled with values or left blank as appropriate. If a subject has two or more values for a predicate, the value(s) will appear on subsequent row(s). This manner of unique columns and minimal yet distinct subject rows corresponds to normalization principles of relational databases.


sswap.info/api
HTTP API for conversion of JSON specifications into SSWAP Resource Graphs and ontology types and properties
GET /api Home page of the self-documenting HTTP API
Example:
GET /api/makePDG For translating JSON into an RDF/XML OWL PDG (Provider Description Graph)
GET /api/makeRDG For translating JSON into an RDF/XML OWL RDG (Resource Description Graph)
GET /api/makeRIG For translating JSON into an RDF/XML OWL RIG (Resource Invocation Graph)
GET /api/makeRRG For translating JSON into an RDF/XML OWL RRG (Resource Response Graph)
GET /api/makeRQG For translating JSON into an RDF/XML OWL RQG (Resource Query Graph)
GET /api/makeType For translating JSON into an RDF/XML OWL type (OWL Class) ontology term
GET /api/makeProperty For translating JSON into an RDF/XML OWL predicate (OWL Property) ontology term
GET /api/JSONSyntax JSON syntax and semantics
Examples:
POST /api Translates JSON document (content of the POST body) into OWL DL RDF/XML per the "api" end-point directive
Examples:
  • command line: curl -d@myRDG.json http://sswap.info/api where myRDG.json is the JSON file for translation into a RDG
  • command line: curl -d@myType.json http://sswap.info/api where myType.json is the JSON file for translation into an OWL class
POST /api/... Any of the GET end-points above (except /JSONSyntax) for direct translation
Examples:
  • command line: curl -d@myRDG.json http://sswap.info/api/makeRDG where myRDG.json is the JSON file for translation into a RDG
  • command line: curl -d@myType.json http://sswap.info/api/makeType where _myType.json is the JSON file for translation into an OWL class
  • Engage the API from your browser at sswap.info/make (see /make above)
  • Allows developers to write SSWAP Resource Graphs and ontology terms in "non-semantic" JSON and have them translated into "semantic" W3C RDF/XML OWL DL
  • If the "api" directive is specified in the JSON file, then the file can be POSTed to sswap.info/api and it will be directed to its respective end-point
  • Input format must be JSON following the syntax and semantics as described at sswap.info/api; generic JSON is not translatable
  • On success, format is W3C RDF/XML OWL DL