Updating README.md
This commit is contained in:
parent
8be91c9580
commit
93011fc505
260
README.md
260
README.md
@ -25,82 +25,208 @@ suspends graphical applications running in the background, thus preventing Anki
|
|||||||
Until this problem is resolved, users of this Mac OS X will have to keep both the browser window and Anki on-screen.
|
Until this problem is resolved, users of this Mac OS X will have to keep both the browser window and Anki on-screen.
|
||||||
Sorry for the lameness; I am researching a fix for this issue.
|
Sorry for the lameness; I am researching a fix for this issue.
|
||||||
|
|
||||||
## API ##
|
## Application Interface ##
|
||||||
|
|
||||||
Ankiconnect accepts HTTP POST request with POST body in JSON format, and then return an id(version id/ note id) or a list(decks, models and fields) as response data.
|
AnkiConnect exposes Anki features to external applications via an easy to use
|
||||||
|
[RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API. After it is installed, this plugin will
|
||||||
|
initialize a minimal HTTP sever running on port 8765 every time Anki executes. Other applications (including browser
|
||||||
|
extensions) can then communicate with it via HTTP POST requests.
|
||||||
|
|
||||||
|
### Sample Invocation ###
|
||||||
|
|
||||||
|
Every request consists of an *action*, and a set of contextual *parameters*. A simple example of a JavaScript
|
||||||
|
application communicating with the extension is illustrated below:
|
||||||
|
|
||||||
### Request URI:
|
|
||||||
```JavaScript
|
```JavaScript
|
||||||
var uri = http://127.0.0.1:8765
|
function ankiInvoke(action, params={}) {
|
||||||
```
|
return new Promise((resolve, reject) => {
|
||||||
|
const xhr = new XMLHttpRequest();
|
||||||
|
xhr.addEventListener('loadend', () => {
|
||||||
|
if (xhr.responseText) {
|
||||||
|
resolve(JSON.parse(xhr.responseText));
|
||||||
|
} else {
|
||||||
|
reject('unable to connect to plugin');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
### Request Method:
|
xhr.open('POST', 'http://127.0.0.1:8765');
|
||||||
**HTTP POST**
|
xhr.send(JSON.stringify({action, params}));
|
||||||
|
});
|
||||||
### JS call example:
|
|
||||||
```JavaScript
|
|
||||||
var xhr = $.post(uri, postdata, (response, status) => {});
|
|
||||||
```
|
|
||||||
|
|
||||||
### POST body & response
|
|
||||||
#### Check Version:
|
|
||||||
```JavaScript
|
|
||||||
var postdata = {action: "version", params: {}}
|
|
||||||
var response = "1" //current anki connect version
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Retrieve deck name list:
|
|
||||||
```JavaScript
|
|
||||||
var postdata = {action: "deckNames", params: {}}
|
|
||||||
var response = ["test deck 1","test deck 2"] //all decks name list
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Retrieve model name list:
|
|
||||||
```JavaScript
|
|
||||||
var postdata = {action: "modelNames", params: {}}
|
|
||||||
var response = ["basic","basic (and reversed card)"] //all models name list
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Retrieve fields list for specified model:
|
|
||||||
```JavaScript
|
|
||||||
var postdata = {action: "modelFieldNames", params: {modelName: "basic"}}
|
|
||||||
var response = ["front","back"] //fields name list
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Check if can add note or not (empty or duplicated card )
|
|
||||||
```JavaScript
|
|
||||||
var postdata = {
|
|
||||||
action: "canAddNotes",
|
|
||||||
params: {
|
|
||||||
notes: [
|
|
||||||
{deckName: "test deck 1", modelName: "basic", fields: {...}, tags:[]},
|
|
||||||
{deckName: "test deck 1", modelName: "basic", fields: {...}, tags:[]},
|
|
||||||
{deckName: "test deck 1", modelName: "basic", fields: {...}, tags:[]}
|
|
||||||
// for fields:{...}, please check below for detail.
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
var response = [true, true, true] // a list of result, say if this note can be added or not.
|
|
||||||
|
ankiInvoke('version').then(response => {
|
||||||
|
window.alert(`detected API version: ${response}`);
|
||||||
|
}).catch(error => {
|
||||||
|
window.alert(`could not get API version: ${error}`);
|
||||||
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Add note
|
### Supported Actions ###
|
||||||
```JavaScript
|
|
||||||
var postdata = {
|
The following actions are currently supported:
|
||||||
action: "addNote",
|
|
||||||
params: {
|
* `version`
|
||||||
deckName: "test deck 1",
|
|
||||||
modelName: "basic",
|
Gets the version of the API exposed by this plugin. Currently only version `1` is defined.
|
||||||
note: {
|
|
||||||
fields: {
|
This should be the first call you make to make sure that your application and AnkiConnect are able to communicate
|
||||||
front: "front content",
|
properly with each other. New versions of AnkiConnect will backwards compatible; as long as you are using actions
|
||||||
back: "back content"
|
which are available in the reported AnkiConnect version or earlier, everything should work fine.
|
||||||
},
|
|
||||||
tags: ["tag1","tag2"]
|
**Sample request**:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
action: 'version',
|
||||||
|
params: {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sample response**:
|
||||||
|
```
|
||||||
|
1
|
||||||
|
```
|
||||||
|
* `deckNames`
|
||||||
|
|
||||||
|
Gets the complete list of deck names for the current user.
|
||||||
|
|
||||||
|
**Sample request**:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
action: 'deckNames',
|
||||||
|
params: {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sample response**:
|
||||||
|
```
|
||||||
|
[
|
||||||
|
'Default',
|
||||||
|
/* ... */
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
* `modelNames`
|
||||||
|
|
||||||
|
Gets the complete list of model names for the current user.
|
||||||
|
|
||||||
|
**Sample request**:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
action: 'modelNames',
|
||||||
|
params: {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sample response**:
|
||||||
|
```
|
||||||
|
[
|
||||||
|
'Basic',
|
||||||
|
'Basic (and reversed card)',
|
||||||
|
/* ... */
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
* `modelFieldNames`
|
||||||
|
|
||||||
|
Gets the complete list of field names for the provided model name.
|
||||||
|
|
||||||
|
**Sample request**:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
action: 'modelFieldNames',
|
||||||
|
params: {
|
||||||
|
modelName: 'Basic'
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
```
|
||||||
var response = note id(success) or null(fail)
|
|
||||||
```
|
**Sample response**:
|
||||||
|
```
|
||||||
|
[
|
||||||
|
'Front',
|
||||||
|
'Back',
|
||||||
|
/* ... */
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
* `addNote`
|
||||||
|
|
||||||
|
Creates a note for the given deck and model, with the provided field values and tags. Returns the identifier of the
|
||||||
|
created note created on success, and `null` on failure.
|
||||||
|
|
||||||
|
AnkiConnect can download audio files and embed them in newly created notes. The corresponding *audio* note member is
|
||||||
|
optional and can be omitted. If you choose to include it, the *url* and *filename* fields must be also defined. The
|
||||||
|
*skipHash* field can be optionally provided to skip the inclusion of downloaded files with an MD5 hash that matches
|
||||||
|
the provided value. This is useful for avoiding the saving of error pages and stub files.
|
||||||
|
|
||||||
|
**Sample request**:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
action: 'addNote',
|
||||||
|
params: {
|
||||||
|
deckName: 'Default',
|
||||||
|
modelName: 'Basic',
|
||||||
|
note: {
|
||||||
|
fields: {
|
||||||
|
Front: 'front content',
|
||||||
|
Back: 'back content',
|
||||||
|
/* ... */
|
||||||
|
},
|
||||||
|
tags: [
|
||||||
|
'yomichan',
|
||||||
|
/* ... */
|
||||||
|
],
|
||||||
|
audio: /* optional */ {
|
||||||
|
url: 'https://assets.languagepod101.com/dictionary/japanese/audiomp3.php?kanji=猫&kana=ねこ',
|
||||||
|
filename: 'yomichan_ねこ_猫.mp3',
|
||||||
|
skipHash: '7e2c2f954ef6051373ba916f000168dc'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sample response**:
|
||||||
|
```
|
||||||
|
null
|
||||||
|
```
|
||||||
|
* `canAddNotes`
|
||||||
|
|
||||||
|
Accepts an array of objects which define parameters for candidate notes (see `addNote`) and returns an array of
|
||||||
|
booleans indicating whether or not the parameters at the corresponding index could be used to create a new note.
|
||||||
|
|
||||||
|
**Sample request**:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
action: 'canAddNotes',
|
||||||
|
params: {
|
||||||
|
notes: [
|
||||||
|
deckName: 'Default',
|
||||||
|
modelName: 'Basic',
|
||||||
|
note: {
|
||||||
|
fields: {
|
||||||
|
Front: 'front content',
|
||||||
|
Back: 'back content',
|
||||||
|
/* ... */
|
||||||
|
},
|
||||||
|
tags: [
|
||||||
|
'yomichan',
|
||||||
|
/* ... */
|
||||||
|
]
|
||||||
|
}
|
||||||
|
/* ... */
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sample response**:
|
||||||
|
```
|
||||||
|
[
|
||||||
|
true,
|
||||||
|
/* ... */
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
## License ##
|
## License ##
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user