A RESTful InPhO API ¶

We are committed to open access, with data available via a REST API, a monthly OWL archive of the ontology, visualizations and datafiles posted on our datablog, and source code at GitHub. All data uses the Creative Commons BY-NC-SA 3.0 license.

InPhO maintains an open-access application platform interface (API) to facilitate collaboration with digital humanities and semantic web programmers. This API is built upon the principles of REpresentational State Transfer (REST), a paradigm of web service development which leverages the ubiquotus HTTP protocol to provide a common interface for object manipulation.

Every idea, thinker and journal in the InPhO knowledge base may be retrieved in both a human-readable HTML page and a machine-readable JSON object. Entities may be manipulated through the four basic HTTP Request Methods: POST (create), GET (retrieve/list), PUT (update), DELETE. Authentication is handled through HTTP Basic Authentication over a secure SSL connection. Due to the stateless nature of a RESTful web service, each request is completely self-contained, eliminating the need for session scoping.

A detailed technical specification is below:

API Structure ¶

URI	GET	PUT	POST	DELETE
/entity	list	–	–	–
/entity/{id}	view	–	–	–
/idea	list	–	create	–
/idea/{id}	view	update	–	delete
/idea/{id}/graph	view	–	–	–
/idea/{id}/{relation}	list	–	–	–
/idea/{id}/{relation}/{id2}	–	update	create	delete
/thinker	list	–	create	–
/thinker/{id}	view	update	–	delete
/thinker/{id}/graph	view	–	–	–
/thinker/{id}/{relation}/{id2}	–	update	create	–
/journal	list	–	create	–
/journal/{id}	view	update	–	delete
/school_of_thought	list	–	–	–
/school_of_thought/{id}	view	–	–	–
/work	list	–	–	–
/work/{id}	view	–	–	–
/taxonomy	list	–	–	–
/taxonomy/{id}	view	–	–	–

Adding a file extension will return the appropriate format for GET requests. Currently implemented:

URI	default	html	json	xml
/entity	html	y	y	–
/entity/{id}	html	y	y	–
/idea	html	y	y	–
/idea/{id}	html	y	y	–
/idea/{id}/graph	html	y	y	–
/idea/{id}/{relation}	html	y	y	–
/idea/{id}/{relation}/{id2}	–	–	–	–
/thinker	html	y	y	–
/thinker/{id}	html	y	y	–
/thinker/{id}/graph	html	y	y	–
/thinker/{id}/{relation}/{id2}	–	–	–	–
/journal	html	y	y	–
/journal/{id}	html	y	y	–
/taxonomy	html	y	y	–
/taxonomy/{id}	html	y	y	–
/school_of_thought	html	y	y	–
/school_of_thought/{id}	html	y	y	–
/work	html	y	y	–
/work/{id}	html	y	y	–

Thinker-Thinker {relation}s: influenced, influenced_by, teacher_of, student_of
Idea-Idea {relation}s: classes, instances, links, hyponyms, related FIX: generality, relatedness
Idea {relation}s: FIX: nationality, profession

Response Codes ¶

Code using our platform should handle the 6 HTTP Responses below for all Methods, unless otherwise noted.

HTTP 200 OK: Request processed, success
HTTP 400 Bad Request: Only for: POST, PUT Request did not validate (ex: teacher_of can only have a degree of 0 or 1 (y/n) - if degree=3 you will get an HTTP 400)
HTTP 401 Unauthorized: Only for: Permissioned methods (see chart below) Unable to be authorized, self explanatory.
HTTP 404 Not Found: One of the ids passed was invalid, so the resource could not be found
HTTP 405 Method Not Allowed: The URL does not support the request method. (ex: Using GET on an evaluation url)
HTTP 409 Conflict: Only for: POST, PUT Valid request, but there are conflicts (ex. creating a journal with an ISSN that is already in the db)
HTTP 500 Internal Server Error: Thrown if there are currently issues with the InPhO service.

Permissions ¶

There are five levels of authentication - from most restrictive to least restrictive, each role has the privileges of all lesser roles:

public	GET
user	evaluation POST
creator	evaluation PUT, DELETE
curator	entity PUT, POST, DELETE
admin	all permissions

Request Parameters ¶

GET Parameters ¶

/idea, /journal, /entity, /taxonomy, /thinker, /work, /school_of_thought: string: sep, q boolean: redirect int: limit

POST/PUT Parameters ¶

/journal/{id}: String: ISSN, URL boolean: openAccess, student, active (pass blank for false - ex. “?openAccess=&student=&active=”)
/idea, /journal, /entity, /taxonomy, /thinker, /work, /school_of_thought: String: sep_dir
/idea/{id}, /journal{id}, /entity{id}, /taxonomy{id}, /thinker{id}, /work{id}, /school_of_thought{id}: String: sep_dir
/idea/{id}/{related}: boolean: sep_filter
/idea/{id}/{relation}/{id2}: int: degree (0:4)
/thinker/{id}}/{relation}/{id2}: int: degree (0:4)

Quick Start ¶

The quickest way to get started is to use the command line tool curl:

GET

curl https://inpho.cogs.indiana.edu/idea/646

To send a query for a specific SEP directory

PUT

curl -X PUT -d "degree=1" -u username:password https://inpho.cogs.indiana.edu/thinker/3724/teacher_of/2553

For platforms which do not support the PUT method (including HTML4 forms), one can make a POST request with the parameter _method=PUT which will be translated to the appropriate request on the server-side:

curl -d "_method=PUT&degree=3" -u username:password https://inpho.cogs.indiana.edu/thinker/3724/teacher_of/2553

POST

curl -X POST -d "label=epistemology" -u username:password https://inpho.cogs.indiana.edu/idea

DELETE

curl -X DELETE -u username:password https://inpho.cogs.indiana.edu/thinker/3724/teacher_of/2553 curl -X DELETE -u username:password https://inpho.cogs.indiana.edu/idea/715

Development ¶

Developers may use any language to code against the API, provided they use the HTTP protocol. These are some reccommended url libraries for common development languages:

PHP	curl
Python	urllib
Perl	WWW::curl
Ruby	Net::HTTP
C	libcurl
C++	curlpp
C#	System.Net.HttpWebRequest
Java	HttpClient
Common Lisp	AllegroServe
JavaScript	XMLHttpRequest
JavaScript	jQuery.Post jQuery.Ajax [useful notes on PUT and DELETE]
JavaScript	YAHOO.util.Connect.asyncRequest [example] [docs]

Testing ¶

InPhO maintains a separate server for development testing. Applications should be tested on http://inphodev.cogs.indiana.edu:8088/ before switching to https://inpho.cogs.indiana.edu/. InPhOdev maintains a separate database to avoid data pollution issues during development. The data is periodically replaced with the newest data from InPhO.

More REST Resources ¶

Building Web Services the REST Way - Concise, high-quality introduction
Wikipedia - Representational State Transfer - Good summary, but does not include examples.
A Brief REST Introduction - Comprehensive introduction, but not as brief as the title implies
RESTify-DayTrader - Good example of using REST
Representational State Transfer (REST) The original chapter from Roy Feldings’s dissertation

InPhO API Docs