Skip to content

Endpoints

Jump to bottom
Don Cato edited this page Mar 4, 2024 · 6 revisions

Clients that want to work with the Freemind API Server will do so by sending requests to various endpoints. The available endpoints and their proper use is described on this page.

All endpoints support only the POST request. For authentication two headers should be provided within the request:

  • The token with the api access token as it's value
  • The user with the username as it's value

A useful tool for testing is cURL one could perform an example request with it like this:

curl -X POST -H "user: <USER>" -H "token: <TOKEN>" http://127.0.0.1:8008/xml/fetch

How to work with tokens and users will be described on a different page

Generic Endpoints

Endpoints in this section return plain text or alternatively nothing.

checksum

  • /checksum/{algorithm}

Params:

  • algorithm: The algorithm to use. Can be either md5 or sha1

Calculates the checksum of your full XML document according to the provided algorithm and returns the result in plain text

session

  • /session/auth
  • /session/extend

Params:

  • None

/session/auth creates a new session token and returns it in plain text as the body, this token can then be used for authentication instead of a password (a username still needs to be provided). This token will expire (default is after 5min but that might be subject to change). When using this token to authenticate against any endpoint it's expiry automatically extended, provided it is still valid.

/session/extend will return nothing and will extend the tokens expiry will be extended by twice of the normal amount (so when the default is 5min this endpoint will extend the token to be valid for 10min).

XML Endpoints

All XML Endpoints return as their response bodies XML Documents, if any.

XML Fetch

  • /xml/fetch

Returns the full XML document on the authenticated user in the response body. If there was no XML document available to the server it returns a minimal version.

XML Update

  • /xml/update

Accepts a full XML document as request Body and saves it. It is used to push changes to the server. The Server performs a sort of validation before it is accepted, if the validation fails no changes will be performed. The validation performed is the same that is done when using the /xml/validate endpoint.

XML Validate

  • /xml/validate

Accepts a full XML document as request Body and validates it.

Please Note that the validation is little guarantee for anything. However it checks that:

  • exactly one registry is present
  • that each entry / directory has an unique id

This endpoint is supposed to be a kind of dry-test for the update endpoint, as it will never perform any actual changes to the stored data.

XML Get By ID

  • /xml/get_by_id/{id}

Params:

  • id: The ID of the element to be returned.

returns a partial XML document containing only the entry or directory which matches the given id.

XML Filter Name & Value

  • /filter/{name}/{value}

Params:

  • name: Name
  • value: Value

Returns only entries and directories (aka. elements) which contain a sub-node with the supplied name and value. You can provide an asterisk (*) as a wildcard in the value to match only names.

This function should (and most likely will) also match sub-sub-nodes etc. (e.g.: a search for the name 'pick' and an entry with the structure 'entry->note->meta->pick' will match the entry (same goes for directories))

XML Priority Helper

  • /priority/{priority}
  • /priority/highest

(Note that the 'highest' priority (e.g. the most important task) has the lowest priority value)

All of these filter elements by their priority sub-node (these endpoints use the same function as the filter endpoint, so both have similar behavior). Obviously these endpoints only return elements which have a 'priority' sub-node set with a valid value in it.

The highest endpoint will first find the lowest value of all priority sub-nodes and will then only return nodes whose priority matches the found value

The {priority} endpoint will accept a custom numerical value. It will then filter only for events which numerical priority is lower or equal than the provided one.

XML Due helpers

  • /due/over
  • /due/today
  • /due/tomorrow
  • /due/in/{start}/{end}

All of these filter elements by their due sub-node (these endpoints use the same function as the filter endpoint, so both have similar behavior). Obviously these endpoints only return elements which have a 'due' sub-node set with a valid value in it.

The 'over' endpoint returns all elements which due date was in the past (before the current day at midnight).

The 'today' endpoint returns all elements which due is on the current day and the 'tomorrow' endpoint only returns elements which due date is on tomorrow.

With the last endpoint you can specify your own range as two UNIX timestamps, any elements which due date falls in between the supplied start and end is returned. The UNIX timestamp is worked with as a u32. If 0 is supplied as the end value it is replaced with the maximum value. Meaning if you'd wish to catch all elements with any due date you could do so with /xml/due/in/0/0

Clone this wiki locally