Skip to content
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.

WIP Produce the simplest-possible getting started guide for the Bisq HTTP API #54

Closed
wants to merge 16 commits into from
Closed

WIP Produce the simplest-possible getting started guide for the Bisq HTTP API #54

Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
95a2f88
Add 'Monitoring Bisq offers with the Bisq HTTP API'
May 11, 2018
e778141
Apply source highlighting
cbeams May 17, 2018
37f2b19
Favor one line per paragraph
cbeams May 17, 2018
70ce251
Remove unnecessary blank lines
cbeams May 17, 2018
7ee80ee
Render literal text with `backticks` where appropriate
cbeams May 17, 2018
ae5b54a
Edit for grammar, style and clarity
cbeams May 17, 2018
24ffd06
Use --appName to avoid collision with default Bisq app
cbeams May 17, 2018
eea7498
Verify the API is up with 'version' endpoint
cbeams May 17, 2018
911f6ca
Apply cbeams comments
May 21, 2018
17a48d1
Add note about appName parameter.
May 23, 2018
d73a565
Cleanup json snippets
May 23, 2018
b73db83
Add JDK and JavaFX to requirements section.
May 23, 2018
10be120
Merge branch 'master' into http-api-monitor
cbeams Jun 29, 2018
7d8e78c
Remove now-global attributes from header
cbeams Jun 29, 2018
7eb1466
Refine text, headings and admonitions
cbeams Jun 29, 2018
56d3185
Implement basic copy edits
Jun 30, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
22 changes: 11 additions & 11 deletions http-api-monitor-offers.adoc
View file
Open in desktop
Expand Up @@ -23,7 +23,7 @@ NOTE: Using the Bisq HTTP API in no way requires the use of NodeJS on the client

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Right about here we should do an INFO admonition that lets the user know that the Bisq HTTP API is currently incubating, and that this means things may be a bit rough around the edges, that their feedback is extra appreciated, along with pointers about how to provide that feedback. You may just direct them to the "next steps" section at bottom where they can find out more about providing feedback (see my related comment about 'next steps' below).

== Run the API

There are two alternative ways you can run an instance of the Bisq HTTP API, either from a Docker image or from source.
There are two ways you can run an instance of the Bisq HTTP API: from a Docker image or from source.

=== Run the API using Docker

Expand All @@ -42,12 +42,12 @@ For more hard-core developers that want to run from source:
-Dexec.args="--appName=http-api-monitor-offers"

[NOTE]
Since the API is in incubating phase we suggest to run it against different database directory then the default one.
To do that, use `--appName` parameter. You can set it to whatever you like, just keep it different from `Bisq`.
Since the API is incubating we suggest to run it against a different database directory from the default one.
To do that, use the `--appName` parameter. You can set it to whatever you like (just keep it different from `Bisq`).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Right about here we should do an INFO admonition that explains why they're having to run a separate instance of Bisq to experiment with the HTTP API. It's going to be confusing as hell for users who have a perfectly good Bisq client already up and running locally to spin up a different, unrelated instance, unless they have that explained to them. I'd just explain it very clearly in the context of this being an "incubating" project, and that when the the project comes out of incubation, this functionality will be integrated directly into the official Bisq client you run locally. In the meantime, you need to spin up a separate instance to experiment with (and provide feedback on!) this incubating project.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

=== Verify the API is running

In both cases the API should be running on port 8080. You can verify that by executing:
The API should now be running on port 8080. You can verify that by executing:

curl http://localhost:8080/api/v1/version

Expand All @@ -69,7 +69,7 @@ Complete interactive API documentation is available at http://localhost:8080/swa

== API overview

First we will look at the endpoints we need to fetch the data from and how they responses look like.
First we will look at the endpoints we need to fetch the data from and how their responses look.

=== List available offers

Expand All @@ -85,7 +85,7 @@ The response should look like this:
}
----

Where `offers` is an array with individual offers and `total` is number of all offers. The model for each individual `OfferDetail` is defined as follows:
The `offers` property is an array with individual offers and `total` is the number of all offers. The model for each `OfferDetail` element is defined as follows:

[source,json]
----
Expand Down Expand Up @@ -132,7 +132,7 @@ Where `offers` is an array with individual offers and `total` is number of all o

Now let's assume that we want to buy bitcoin, and let's define "interesting" offers as those that:

. sell bitcoin at a discount 1% or more under the current market price, and
. sell bitcoin at a 1% discount or more under the current market price, and
. accept payment in Euros to a Polish SEPA account

First we need to filter those offers using following static criteria:
Expand All @@ -147,7 +147,7 @@ First we need to filter those offers using following static criteria:
}
----
Copy link
Member Author

@cbeams cbeams May 17, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • This result and the "we need to filter those offers" language above again make me as a reader feel like I'm supposed to do something with this information. There is actually no "step" here, it's just for informational / context purposes, and that's fine, but it should be made more clear. For example, you can say something like:

We'll need to filter our offers using the static criteria you see below:

[json snippet]

In the sections that follow, we'll do just that with a combination of data returned from Bisq HTTP API endpoint calls and programmatic filtering.

(Very quickly written, but you get the idea)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

List available offers and Get the market price parts are just describing how the API looks like.
I wanted to first give API overview and then dive into the javascript.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've introduced API overview section and those List available offers and Get the market price are now subsections so it should be clear for the user that they don't need to do anything there.


Next we need to filter those offers by price. There are two types of offers: _market-based price offers_ and _fixed price offers_. They are distinguished by the `useMarketBasedPrice` attribute. In case of market-based price offers the filtering criteria is easy: the `marketPriceMargin` value must be above 0.1. In case of fixed price offers we have to fetch market price of BTC in EUR, then calculate whether the price is 1% or less, and finally we must filter offers which have a price _less_ than that calculated price.
Next we need to filter those offers by price. There are two types of offers: _market-based price offers_ and _fixed price offers_. They are distinguished by the `useMarketBasedPrice` attribute. In the case of market-based price offers the filtering criteria is easy: the `marketPriceMargin` value must be above 0.1. In the case of fixed price offers we have to fetch the market price of BTC in EUR, calculate whether the price is 1% or less, and then filter offers which have a price _less_ than that calculated price.
Copy link
Contributor

@m52go m52go Jun 30, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"On Bisq, there are two types of offers..." [Suggestion]

"In the case of fixed price offers we have to fetch the market price of BTC in EUR, calculate a threshold price that fits our needs (i.e., the price that's 1% lower than the market price), and then find all offers which have a price less than that threshold price." [Suggestion—I found this wording confusing]


=== Get the market price

Expand Down Expand Up @@ -181,9 +181,9 @@ In general our script will look like this:
include::http-api-monitor-offers.js[tags=flow]
----

So first 2 things to do (concurrently and asynchronously) is to fetch offers and market price of BTC from our API. Then we need to filter those offers and finally display the results.
So first 2 things to do (concurrently and asynchronously) is to fetch offers and market price of BTC from our API. Then we need to filter those offers and display the results.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure "(concurrently and asynchronously)" adds any value.


Getting offers is a simple call that returns promise with array of offers:
Getting offers is a simple call that returns a promise with an array of offers:

.http-api-monitor-offers.js
[source,javascript]
Expand All @@ -207,7 +207,7 @@ Now our `filterOffers` function is ready to receive an array of results from the
include::http-api-monitor-offers.js[tags=filterOffers]
----

This function filters offers to match our criteria. It returns matching offers and maps them to a bit simpler structure that contains as little data as needed for `notify` function. We are using `lodash` library to simplify the filtering.
This function filters offers to match our criteria. It returns matching offers and maps them to a simpler structure that contains as little data as needed for the `notify` function. We are using the `lodash` library to simplify filtering.

The `getPriceFilter` function creates the actual filter function and looks like this:

Expand Down