Lightweight, Markdown supported, note taking tool written in .NET core.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
webapp
.gitignore
Doxyfile
README.md
appveyor.yml

README.md

Wolk

The project is released under the MIT license.

Wolk (wolk is Dutch for "cloud") is a little, open source, piece of software, completely written in C# (using .NET Core). It is a standalone application that uses SQLite as database. You can type your notes in the simple and enjoyable Markdown language. The API is completely Restful, so you can build your own client if you don't like the default one! Need a personal, cloud-based notetaking program with just enough functionalities? Download and install Wolk now!

Installation

You can grab one of the releases or build your own release of Wolk.

Building and debugging it yourself (only Windows for now)

  • Make sure you have the latest code.
  • You can open the project in Visual Studio.
  • The project Wolk.Web contains the actual web application.

Installing a release

  • Make sure you have the latest code.
  • Execute the script build.ps1 (additionally edit the script to make a release build for other systems than Windows).
  • In webapp/src/Wolk.Web/bin/Release you can find the build result.
  • This is a standalone application and can be started right away.
  • If you install this script on your server and you have a custom (sub)domain, make sure you create a reverse proxy in your Apache or Nginx (or any other server), so your domain (e.g. notes.ducode.org) points to http://localhost:4000/ (or any other port number you've configured).

API

Wolk has a small but effective Restful API for manipulating the notes. Here you see all calls (if you want to play with the API right away, I've included the file rest_calls.json which you can import in Postman.

Authentication

With every request, a basic authentication header should be sent. Let's say your username is user and your password pass, then the HTTP authentication header will be this:

Authorization: Basic dXNlcjpwYXNz

The code behind "Basic" is a Base64 encoded string of "user:pass".


POST and PUT requests

The data for the POST and PUT requests should be sent as JSON strings with content type "application/json".

Check user

URL: http://wolk/api/users/:username

A route to check the credentials for user :username. If the username and password (provided through the Authorization header) aren't correct, a header 401 is sent back.

{
    "username":"wolk"
}

Returned status codes:

  • 200: if OK
  • 401: if authorization data is incorrect
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get note

URL: http://wolk/api/notes/:id?updateOpened=1

  • updateOpened (optional): whether the datetime_opened field should be updated or not (1 if it needs to be updated, 0 if it doesn't need to be updated)

Returns a note with a specific :id.

Example response:

{
    "id": 83,
    "title": "#.net #tech base 64 encode and decode",
    "content": "This is the content",
    "datetime_opened": "2015-08-14T22:53:16.000Z",
    "datetime_added": "2015-08-12T21:29:49.000Z",
    "datetime_updated": null,
    "secret_code":"123",
    "archived": false
}
  • 200: if OK
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get all notes

URL: http://wolk/api/notes?includeContent=1

  • includeContent (optional): whether the content tag in the response should be set
  • term (optional): the search term. If this variable is set, the result set will be filtered on the search term.
  • cap (optional): how many notes should be returned.
  • page (optional): the page of the notes, only makes sense when you've filled in a cap.
  • noteRetrieve (optional): which notes should be retrieved (0 = retrieve all notes, 1 = retrieve archived notes, 2 = retrieve non archived notes)

Returns all notes in the database.

Example response:

[{
    "id": 83,
    "title": "#.net #tech base 64 encode and decode",
    "content": "This is the content",
    "datetime_opened": "2015-08-14T22:53:16.000Z",
    "datetime_added": "2015-08-12T21:29:49.000Z",
    "datetime_updated": null,
    "secret_code":"123",
    "archived": false
},{
    "id": 84,
    "title": "#.net #tech base 64 encode and decode",
    "content": "This is the content",
    "datetime_opened": "2015-08-14T22:53:16.000Z",
    "datetime_added": "2015-08-12T21:29:49.000Z",
    "datetime_updated": null,
    "secret_code":"123",
    "archived": false
}]
  • 200: if OK
  • 401: if authorization data is incorrect
  • 500: if something went horribly wrong (e.g. the database is unreachable)

(POST) Add note

URL: http://wolk/api/notes

Parameters:

  • title: the note title
  • content: the note content

Adds a new note to the database.

Example response:

{
    "id": 83,
    "title": "#.net #tech base 64 encode and decode",
    "content": "This is the content",
    "datetime_opened": "2015-08-14T22:53:16.000Z",
    "datetime_added": "2015-08-12T21:29:49.000Z",
    "datetime_updated": null,
    "secret_code":"123",
    "archived": false
}

The new note as JSON object is returned.

Returned status codes:

  • 200: if OK
  • 400: if the input data is incorrect
  • 401: if authorization data is incorrect
  • 500: if something went horribly wrong (e.g. the database is unreachable)

(PUT) Update note

URL: http://wolk/api/notes/:id

Parameters:

  • title: the note title
  • content: the note content

Edits a note with a specific :id.

Example response: No content is returned.

Returned status codes:

  • 204: if OK
  • 400: if the input data is incorrect
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

(DELETE) Delete note

URL: http://wolk/api/notes/:id

Deletes a note with a specific :id.

Example response: No content is returned.

  • 204: if OK
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

(PUT) Archive note

URL: http://wolk/api/notes/:id/archive

Marks a note with id :id as archived. If the note is already archived, this call will unarchive the note.

Example response: No content is returned.

  • 204: if OK
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get tags

URL: http://wolk/api/tags

Returns all available tags in the database.

Example response:

[{
    "id": 84613,
    "name": ".net"
},
{
    "id": 84618,
    "name": "xampp"
}]

Returned status codes:

  • 204: if OK
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get file

URL: http://wolk/api/files/:secretCode

This method returns the actual binary as a download. The secret code is calculated when the file was uploaded. This method is not affected by the default basic authentication, to make sharing files easier.

  • 200: if OK
  • 404: if file isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get files by note ID

URL: http://wolk/api/notes/:id/files

Returns all file meta data of a note with specific :id.

Example response:

[{
    "id": 10,
    "note_id": 30,
    "filename": "2014-12-26 13.06.55.jpg",
    "secret_code": "d35cfacc-4416-413c-8196-d88a383da994",
    "datetime_added": "2015-11-04T22:31:54.000Z",
    "content_size": 1370233,
    "mime_type": "image/jpeg"
}]
  • 200: if OK
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get all files

URL: http://wolk/api/files

Returns all file meta data of all files.

Example response:

[{
    "id": 10,
    "note_id": 30,
    "filename": "2014-12-26 13.06.55.jpg",
    "secret_code": "d35cfacc-4416-413c-8196-d88a383da994",
    "datetime_added": "2015-11-04T22:31:54.000Z",
    "content_size": 1370233,
    "mime_type": "image/jpeg"
}]
  • 200: if OK
  • 401: if authorization data is incorrect
  • 500: if something went horribly wrong (e.g. the database is unreachable)

(POST) Add file

URL: http://wolk/api/notes/:id/files

Adds a new file to a note with ID :id. The file should be sent as multipart form data with the name "file". You can also send the file as post data. In this case, you need to post the values base64String (e.g. data:text/plain;base64,VGVzdA==) and filename (e.g. code.txt).

Returned status codes:

  • 200: if OK
  • 400: if uploading went wrong (or if nothing was uploaded at all)
  • 401: if authorization data is incorrect
  • 404: if note isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

(DELETE) Delete file

URL: http://wolk/api/files/:id

Deletes a file with ID :id.

  • 200: if OK
  • 401: if authorization data is incorrect
  • 404: if file isn't found
  • 500: if something went horribly wrong (e.g. the database is unreachable)

Get metadata

URL: http://wolk/api/metadata

Returns some metadata about the system.

Example response:

{
"number_of_notes": 127,
"number_of_tags": 66,
"number_of_files": 12,
"database_size": 11210351,
"datetime_updated": "2016-02-27T09:11:37.000Z"
}
  • 200: if OK
  • 401: if authorization data is incorrect
  • 500: if something went horribly wrong (e.g. the database is unreachable)

View raw note (not RESTful)

URL: http://wolk/notes/raw/:secretCode/:parseType

  • secretCode: the secret code of the note that should be shown
  • parseType:
    • 0: HTML page without parsed Markdown
    • 1: HTML page with parsed Markdown
    • 2: plain text

Addons / plugins

I've developed a few pieces of software for talking to Wolk.