API Introduction

The iKnow! API is fully based on REST standards, but also makes sure that loose integration with techniques like JSON is possible. Right now we provide numerous data feeds and some write-calls that require Authentication + API Key.

Overview of Calls

Call Syntax
 Description API Key?
user profile GET /users/:username
 Who is this user and list their friends. No
study results GET /users/:username/study_results What was this user's score. No
lists studied GET /users/:username/lists What lists/courses did this user study. No
items studied
 GET /users/:username/items What items did this user study. No
recent lists
 GET /lists Recent lists created by the community. No
search lists
 GET /lists/matching/:keyword Search lists. No
create list
 POST /lists Create a new study list. Yes
delete list
 DELETE /lists/:id
 Delete owned list.
 Yes
add item
 POST /lists/:id/items
 Add item or remove item to list.
 Yes
recent items
 GET /items Recent items created by the community. No
search items
 GET /items/matching/:keyword Dictionary lookup. No
items in list
 GET /lists/:id/items Items used in study list. No
create item
 POST /items
 Create a new cue - response pair in any language. Yes
add image
 POST /items/:id/images
 Add image to item. Yes
add sound
 POST /items/:id/sounds
 Add sound to item. Yes
tag item
 POST /items/:id/tags
 Add / remove tags to/from items. Yes
recent sentences
 GET /sentences Recent sentences created by the community. No
search sentences
 GET /sentences/matching/:keyword Find sentences by keyword.
 No
sentences in list
 GET /lists/:id/sentences Get sentences in study list. No
create sentence
 POST /sentences
 Create a new sentence and add to an item/list.
 Yes
add image
 POST /sentences/:id/images
 Add an image to sentence.
 Yes
add sound
 POST /sentences/:id/sounds
 Add a sound to sentence.
 Yes
extract items
 POST /items/extract Extract iKnow! items from a text.
 Yes
sessions
 GET /sessions Get username of logged-in user
 No

Request Structure

The API base URL can be found at http://api.iknow.co.jp/. Here is an example feed for the items of a study list:

http://api.iknow.co.jp/lists/9900/items.xml


Response Formats

Right now, most data can be retreived in XML, HTML, RSS and JSON (with callback). An example of the previous request in JSON with callback will be:

http://api.iknow.co.jp/lists/9900/items.json?callback=update_my_widget


The structure of the response varies per Call, but for study content in XML we use the XMLVocabulary Standard. JSON is a serialization of that same structure.

Calls that require an API Key  

For those calls you need to make sure to include the api_key parameter:

http://api.iknow.co.jp/items/extract.xml?api_key=d6bu49h84yj85z2mgnbh5t4j&text=I record a cd

Error Handling 

When an error occurs, the appropriate HTTP status code will be returned (eg: 403 - Access Denied). The error response looks like this for example:

<?xml version="1.0"?>
<error code="403" message="Access Denied"/>


For the JSON response we always return status 200 OK to make it play well with in-browser Javascript. Example JSON error:

{:error => {:code => 403, :message => 'Access Denied'}}

version 40 as of 1 week ago by nov

Comments