From dc793effce915d256ef5aeec87312b5eaf9c3e79 Mon Sep 17 00:00:00 2001 From: Baptiste Jonglez Date: Wed, 13 Oct 2021 22:54:50 +0200 Subject: [PATCH] Update API doc --- docs/api.rst | 92 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 25 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 93ca36e9..982f828f 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,7 +4,9 @@ The REST API All of what's possible to do with the website is also possible via a web API. This document explains how the API is organized and how you can query it. -The only supported data format is JSON. +The main supported data format is JSON. When using POST or PUT, you can +either pass data encoded in JSON or in ``application/x-www-form-urlencoded`` +format. Overall organisation ==================== @@ -31,7 +33,7 @@ instead of basic auth. For instance, start by generating the token (of course, you need to authenticate):: $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/token - {"token": "eyJwcm9qZWN0X2lkIjoiZGVtbyJ9.M86C3AiZa_SFEyiddYXdTh2-OOI"} + {"token": "WyJ0ZXN0Il0.Rt04fNMmxp9YslCRq8hB6jE9s1Q"} Make sure to store this token securely: it allows full access to the project. For instance, use it to obtain information about the project (replace PROJECT_TOKEN with @@ -47,7 +49,7 @@ looks like:: This token can also be used to authenticate for a project on the web interface, which can be useful to generate invitation links. You would simply create an URL of the form:: - https://ihatemoney.org/authenticate?token=PROJECT_TOKEN + https://ihatemoney.org/demo/join/PROJECT_TOKEN Such a link grants full access to the project associated with the token. @@ -64,10 +66,16 @@ Creating a project A project needs the following arguments: -* ``name``: The project name (string) +* ``name``: the project name (string) * ``id``: the project identifier (string without special chars or spaces) * ``password``: the project password / secret code (string) -* ``contact_email``: the contact email +* ``contact_email``: the contact email (string) + +Optional arguments: + +* ``default_currency``: the default currency to use for a multi-currency project, + in ISO 4217 format. Bills are converted to this currency for operations like balance + or statistics. Default value: ``XXX`` (no currency). :: @@ -75,7 +83,7 @@ A project needs the following arguments: -d 'name=yay&id=yay&password=yay&contact_email=yay@notmyidea.org' "yay" -As you can see, the API returns the identifier of the project +As you can see, the API returns the identifier of the project. Getting information about the project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -88,6 +96,7 @@ Getting information about the project:: "id": "demo", "name": "demonstration", "contact_email": "demo@notmyidea.org", + "default_currency": "XXX", "members": [{"id": 11515, "name": "f", "weight": 1.0, "activated": true, "balance": 0}, {"id": 11531, "name": "g", "weight": 1.0, "activated": true, "balance": 0}, {"id": 11532, "name": "peter", "weight": 1.0, "activated": true, "balance": 5.0}, @@ -151,22 +160,55 @@ You can get the list of bills by doing a ``GET`` on $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/bills -Add a bill with a ``POST`` query on ``/api/projects//bills``. you need the -following params: +Or get a specific bill by ID:: -* ``date``: the date of the bill; defaults to current date if not - provided. (format is ``yyyy-mm-dd``) -* ``what``: what have been payed -* ``payer``: by who ? (id) -* ``payed_for``: for who ? (id, to set multiple id use a list, - e.g. ``["id1", "id2"]``) -* ``amount``: amount payed + $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/bills/42 + { + "id": 42, + "payer_id": 11, + "owers": [ + { + "id": 22, + "name": "Alexis", + "weight": 1, + "activated": true + } + ], + "amount": 100, + "date": "2020-12-24", + "creation_date": "2021-01-13", + "what": "Raclette du nouvel an", + "external_link": "", + "original_currency": "XXX", + "converted_amount": 100 + } + +``amount`` is expressed in the ``original_currency`` of the bill, while +``converted_amount`` is expressed in the project ``default_currency``. +Here, they are the same. + +Add a bill with a ``POST`` query on ``/api/projects//bills``. You need the +following required parameters: + +* ``what``: what has been paid (string) +* ``payer``: paid by who? (id) +* ``payed_for``: for who ? (id). To set multiple id, simply pass + the parameter multiple times (x-www-form-urlencoded) or pass a list of id (JSON). +* ``amount``: amount payed (float) + +And optional parameters: + +* ``date``: the date of the bill (``yyyy-mm-dd`` format). Defaults to current date + if not provided. +* ``original_currency``: the currency in which ``amount`` has been paid (ISO 4217 code). + Only makes sense for a project with currencies. Defaults to the project ``default_currency``. +* ``external_link``: an optional URL associated with the bill. Returns the id of the created bill :: $ curl --basic -u demo:demo -X POST\ https://ihatemoney.org/api/projects/demo/bills\ - -d "date=2011-09-10&what=raclette&payer=31&payed_for=31&amount=200" + -d "date=2011-09-10&what=raclette&payer=1&payed_for=3&payed_for=5&amount=200" 80 You can also ``PUT`` a new version of the bill at @@ -174,7 +216,7 @@ You can also ``PUT`` a new version of the bill at $ curl --basic -u demo:demo -X PUT\ https://ihatemoney.org/api/projects/demo/bills/80\ - -d "date=2011-09-10&what=raclette&payer=31&payed_for=31&amount=250" + -d "date=2011-09-10&what=raclette&payer=1&payed_for=3&payed_for=5&payed_for=1&amount=250" 80 And you can of course ``DELETE`` them at @@ -194,15 +236,15 @@ You can get some project stats with a ``GET`` on $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/statistics [ { - "balance": 12.5, - "member": {"activated": True, "id": 1, "name": "alexis", "weight": 1.0}, - "paid": 25.0, - "spent": 12.5 + "member": {"activated": true, "id": 1, "name": "alexis", "weight": 1.0}, + "paid": 25.5, + "spent": 15, + "balance": 10.5 }, { - "balance": -12.5, - "member": {"activated": True, "id": 2, "name": "fred", "weight": 1.0}, - "paid": 0, - "spent": 12.5 + "member": {"activated": true, "id": 2, "name": "fred", "weight": 1.0}, + "paid": 5, + "spent": 15.5, + "balance": -10.5 } ]