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.
|
||||
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
|
||||
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:
|
||||
**HTTP POST**
|
||||
|
||||
### 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.
|
||||
]
|
||||
}
|
||||
xhr.open('POST', 'http://127.0.0.1:8765');
|
||||
xhr.send(JSON.stringify({action, params}));
|
||||
});
|
||||
}
|
||||
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
|
||||
```JavaScript
|
||||
var postdata = {
|
||||
action: "addNote",
|
||||
params: {
|
||||
deckName: "test deck 1",
|
||||
modelName: "basic",
|
||||
note: {
|
||||
fields: {
|
||||
front: "front content",
|
||||
back: "back content"
|
||||
},
|
||||
tags: ["tag1","tag2"]
|
||||
### Supported Actions ###
|
||||
|
||||
The following actions are currently supported:
|
||||
|
||||
* `version`
|
||||
|
||||
Gets the version of the API exposed by this plugin. Currently only version `1` is defined.
|
||||
|
||||
This should be the first call you make to make sure that your application and AnkiConnect are able to communicate
|
||||
properly with each other. New versions of AnkiConnect will backwards compatible; as long as you are using actions
|
||||
which are available in the reported AnkiConnect version or earlier, everything should work fine.
|
||||
|
||||
**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 ##
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user