From fb758afc8176f998bf665783b70d9a55706234f0 Mon Sep 17 00:00:00 2001 From: Laurent Cozic Date: Tue, 30 Apr 2019 18:58:35 +0100 Subject: [PATCH] Update website --- docs/api/index.html | 145 ++++++++++++----------- docs/changelog/index.html | 223 ++++++++++++++++++------------------ docs/clipper/index.html | 18 +-- docs/debugging/index.html | 40 ++++--- docs/desktop/index.html | 2 +- docs/donate/index.html | 8 +- docs/e2ee/index.html | 8 +- docs/faq/index.html | 47 ++++---- docs/index.html | 146 +++++++++++------------ docs/prereleases/index.html | 2 +- docs/spec/index.html | 30 ++--- docs/stats/index.html | 4 +- docs/terminal/index.html | 157 +++++++++++++------------ 13 files changed, 439 insertions(+), 391 deletions(-) diff --git a/docs/api/index.html b/docs/api/index.html index fcc6fa51a..573b70f60 100644 --- a/docs/api/index.html +++ b/docs/api/index.html @@ -250,55 +250,60 @@ -

Joplin API

-

When the Web Clipper service is enabled, Joplin exposes a REST API which allows third-party applications to access Joplin's data and to create, modify or delete notes, notebooks, resources or tags.

-

In order to use it, you'll first need to find on which port the service is running. To do so, open the Web Clipper Options in Joplin and if the service is running it should tell you on which port. Normally it runs on port 41184. If you want to find it programmatically, you may follow this kind of algorithm:

-
let port = null;
+
Joplin API

+
When the Web Clipper service is enabled, Joplin exposes a REST API which allows third-party applications to access Joplin's data and to create, modify or delete notes, notebooks, resources or tags.

+
In order to use it, you'll first need to find on which port the service is running. To do so, open the Web Clipper Options in Joplin and if the service is running it should tell you on which port. Normally it runs on port 41184. If you want to find it programmatically, you may follow this kind of algorithm:

+
let port = null;
 for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
     const result = pingPort(portToTest); // Call GET /ping
-    if (result == 'JoplinClipperServer') {
+    if (result == 'JoplinClipperServer') {
         port = portToTest; // Found the port
         break;
     }
 }
 

-
Authorisation

+
Authorisation

 
To prevent unauthorised applications from accessing the API, the calls must be authentified. To do so, you must provide a token as a query parameter for each API call. You can get this token from the Joplin desktop application, on the Web Clipper Options screen.

 
This would be an example of valid cURL call using a token:

 
curl http://localhost:41184/notes?token=ABCD123ABCD123ABCD123ABCD123ABCD123
-
In the documentation below, the token will not be specified every time however you will need to include it.

-
Using the API

+
+

In the documentation below, the token will not be specified every time however you will need to include it.

+

Using the API

All the calls, unless noted otherwise, receives and send JSON data. For example to create a new note:

-
curl --data '{ "title": "My note", "body": "Some note in **Markdown**"}' http://localhost:41184/notes
-

In the documentation below, the calls may include special parameters such as :id or :note_id. You would replace this with the item ID or note ID.

+
curl --data '{ "title": "My note", "body": "Some note in **Markdown**"}' http://localhost:41184/notes
+
+

In the documentation below, the calls may include special parameters such as :id or :note_id. You would replace this with the item ID or note ID.

For example, for the endpoint DELETE /tags/:id/notes/:note_id, to remove the tag with ID "ABCD1234" from the note with ID "EFGH789", you would run for example:

curl -X DELETE http://localhost:41184/tags/ABCD1234/notes/EFGH789
-

The four verbs supported by the API are the following ones:

+ +

The four verbs supported by the API are the following ones:

-

Filtering data

+

Filtering data

You can change the fields that will be returned by the API using the fields= query parameter, which takes a list of comma separated fields. For example, to get the longitude and latitude of a note, use this:

curl http://localhost:41184/notes/ABCD123?fields=longitude,latitude
-

To get the IDs only of all the tags:

+ +

To get the IDs only of all the tags:

curl http://localhost:41184/tags?fields=id
-

Error handling

+ +

Error handling

In case of an error, an HTTP status code >= 400 will be returned along with a JSON object that provides more info about the error. The JSON object is in the format { "error": "description of error" }.

-

About the property types

+

About the property types

-

Testing if the service is available

+

Testing if the service is available

Call GET /ping to check if the service is available. It should return "JoplinClipperServer" if it works.

-

Searching

+

Searching

Call GET /search?query=YOUR_QUERY to search for notes. This end-point supports the field parameter which is recommended to use so that you only get the data that you need. The query syntax is as described in the main documentation: https://joplinapp.org/#searching

-

Notes

-

Properties

+

Notes

+

Properties

@@ -431,7 +436,7 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) { - + @@ -445,37 +450,44 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
base_url textIf body_html is provided and contains relative URLs, provide the base_url parameter too so that all the URLs can be converted to absolute ones. The base URL is basically where the HTML was fetched from, minus the query (everything after the '?'). For example if the original page was https://stackoverflow.com/search?q=%5Bjava%5D+test, the base URL is https://stackoverflow.com/search.If body_html is provided and contains relative URLs, provide the base_url parameter too so that all the URLs can be converted to absolute ones. The base URL is basically where the HTML was fetched from, minus the query (everything after the '?'). For example if the original page was https://stackoverflow.com/search?q=%5Bjava%5D+test, the base URL is https://stackoverflow.com/search.
image_data_url
-

GET /notes

+

GET /notes

Gets all notes

-

GET /notes/:id

+

GET /notes/:id

Gets note with ID :id

-

GET /notes/:id/tags

+

GET /notes/:id/tags

Gets all the tags attached to this note.

-

POST /notes

+

POST /notes

Creates a new note

You can either specify the note body as Markdown by setting the body parameter, or in HTML by setting the body_html.

Examples:

-

Creating a note with a specific ID

+

Creating a note with a specific ID

When a new note is created, it is automatically assigned a new unique ID so normally you do not need to set the ID. However, if for some reason you want to set it, you can supply it as the id property. It needs to be a 32 characters long hexadecimal string. Make sure it is unique, for example by generating it using whatever GUID function is available in your programming language.

-
  curl --data '{ "id": "00a87474082744c1a8515da6aa5792d2", "title": "My note with custom ID"}' http://127.0.0.1:41184/notes
-

PUT /notes/:id

+
  curl --data '{ "id": "00a87474082744c1a8515da6aa5792d2", "title": "My note with custom ID"}' http://127.0.0.1:41184/notes
+
+

PUT /notes/:id

Sets the properties of the note with ID :id

-

DELETE /notes/:id

+

DELETE /notes/:id

Deletes the note with ID :id

-

Folders

+

Folders

This is actually a notebook. Internally notebooks are called "folders".

-

Properties

+

Properties

@@ -532,21 +544,21 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
-

GET /folders

+

GET /folders

Gets all folders

The folders are returned as a tree. The sub-notebooks of a notebook, if any, are under the children key.

-

GET /folders/:id

+

GET /folders/:id

Gets folder with ID :id

-

GET /folders/:id/notes

+

GET /folders/:id/notes

Gets all the notes inside this folder.

-

POST /folders

+

POST /folders

Creates a new folder

-

PUT /folders/:id

+

PUT /folders/:id

Sets the properties of the folder with ID :id

-

DELETE /folders/:id

+

DELETE /folders/:id

Deletes the folder with ID :id

-

Resources

-

Properties

+

Resources

+

Properties

@@ -618,23 +630,24 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
-

GET /resources

+

GET /resources

Gets all resources

-

GET /resources/:id

+

GET /resources/:id

Gets resource with ID :id

-

GET /resources/:id/file

+

GET /resources/:id/file

Gets the actual file associated with this resource.

-

POST /resources

+

POST /resources

Creates a new resource

Creating a new resource is special because you also need to upload the file. Unlike other API calls, this one must have the "multipart/form-data" Content-Type. The file data must be passed to the "data" form field, and the other properties to the "props" form field. An example of a valid call with cURL would be:

-
curl -F 'data=@/path/to/file.jpg' -F 'props={"title":"my resource title"}' http://localhost:41184/resources
-

The "data" field is required, while the "props" one is not. If not specified, default values will be used.

-

PUT /resources/:id

+
curl -F 'data=@/path/to/file.jpg' -F 'props={"title":"my resource title"}' http://localhost:41184/resources
+
+

The "data" field is required, while the "props" one is not. If not specified, default values will be used.

+

PUT /resources/:id

Sets the properties of the resource with ID :id

-

DELETE /resources/:id

+

DELETE /resources/:id

Deletes the resource with ID :id

-

Tags

-

Properties

+

Tags

+

Properties

@@ -686,21 +699,21 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
-

GET /tags

+

GET /tags

Gets all tags

-

GET /tags/:id

+

GET /tags/:id

Gets tag with ID :id

-

GET /tags/:id/notes

+

GET /tags/:id/notes

Gets all the notes with this tag.

-

POST /tags

+

POST /tags

Creates a new tag

-

POST /tags/:id/notes

+

POST /tags/:id/notes

Post a note to this endpoint to add the tag to the note. The note data must at least contain an ID property (all other properties will be ignored).

-

PUT /tags/:id

+

PUT /tags/:id

Sets the properties of the tag with ID :id

-

DELETE /tags/:id

+

DELETE /tags/:id

Deletes the tag with ID :id

-

DELETE /tags/:id/notes/:note_id

+

DELETE /tags/:id/notes/:note_id

Remove the tag from the note.