[bisq-network/bisq-docs] Produce the simplest-possible getting started guide for the Bisq HTTP API (#54)

Steve Jain notifications at github.com
Sat Jun 30 15:27:58 UTC 2018


m52go commented on this pull request.

My commit included copy edits and other minor changes. These are more substantive suggestions.

Overall it was very quick and easy...I think it took me less than 15 minutes! Very exciting stuff.

> +
+You should receive a response like the following:
+
+[source,json]
+----
+{
+    "application": "0.6.7",
+    "network": 1,
+    "p2PMessage": 10,
+    "localDB": 1,
+    "tradeProtocol": 1
+}
+----
+
+[NOTE]
+Complete interactive API documentation is available at http://localhost:8080/swagger.

I'd make this stand out a bit more. I don't know if it was just me, but I glazed over it the first few times I saw it. (I also wasn't aware of Swagger, so I just thought it was a cool pathname).

Maybe take it out of a NOTE and make it something like "`*Complete API documentation is available at http://localhost:8080/swagger*. It's interactive, so you can play around with it right in your browser.`"

> +
+You'll build a NodeJS-based script that connects to Bisq over an HTTP API to get offers and market prices and then displays "interesting" offers on the console if any are found.
+
+CAUTION: The Bisq HTTP API is currently incubating. Things may be rough around the edges and should not be considered production-ready. Your feedback is extremely valuable at this stage—see the link:#next-steps[next steps] section at bottom for details how to get in touch with us. Thanks!
+
+
+== What you’ll need
+
+* About 15 minutes
+* A favorite text editor or IDE
+* NodeJS 6+ (to execute the API client script that you will write)
+* Either:
+** Docker (to run from an image) or
+** Git, Maven and JDK8 (to build from source)
+
+NOTE: Using the Bisq HTTP API in no way requires the use of NodeJS on the client side. It is just used for example purposes in this guide.

I suggest removing the parenthetical note above ("to execute the API client script...") and making this note more detailed.

Specifically, explicitly state:

- Node.js is not a dependency of the HTTP API.
- It's only used here to make the tasks of making HTTP requests and manipulating responses easier for the purposes of this example, but that those tasks can be done with any tools the user prefers.

> + . 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:
+
+[source,json]
+----
+{
+    "baseCurrencyCode": "BTC",
+    "counterCurrencyCode": "EUR",
+    "direction": "SELL",
+    "paymentMethodId": "SEPA"
+}
+----
+
+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.

"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 filter offers which have a price _less_ than that threshold price." [Suggestion—I found this wording confusing]

> +
+== Write the monitoring bot code
+
+Let's install some dependencies:
+
+    npm install lodash http-as-promised
+
+In general our script will look like this:
+
+.http-api-monitor-offers.js
+[source,javascript]
+----
+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 display the results.

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

> +
+[source,json]
+----
+{
+  "prices": {
+    "EUR": 7035.62
+  }
+}
+----
+
+
+== Write the monitoring bot code
+
+Let's install some dependencies:
+
+    npm install lodash http-as-promised

Might be helpful to mention adding the `require()` statements here too.

I built the script as I read along, and ended up with errors because I didn't `require()` those modules. It's a super-simple thing that most people will figure out quickly, and I know it's already in the full script at the bottom, but just a quick mention along the lines of "don't forget to require these modules at the top of your script" or something might be nice.

> +* About 15 minutes
+* A favorite text editor or IDE
+* NodeJS 6+ (to execute the API client script that you will write)
+* Either:
+** Docker (to run from an image) or
+** Git, Maven and JDK8 (to build from source)
+
+NOTE: Using the Bisq HTTP API in no way requires the use of NodeJS on the client side. It is just used for example purposes in this guide.
+
+== Run the API
+
+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
+
+The easiest way to run the API in headless mode is by using a Docker image:

Could "headless" be clarified here? Knowing virtually nothing about how this API works, my initial impression was that the API queried my local Bisq client for data, and that 'headless' simply meant 'no GUI' but that's clearly not the case.

Basically I wasn't sure if the API needed my Bisq client to be running in the background.

 A quick 1 or 2 lines about what these images actually do / how the API works might help?

> +//end::getPriceFilter[]
+
+//tag::getMarketPrice[]
+function getMarketPrice() {
+    return $http.get('http://localhost:8080/api/v1/currencies/prices?currencyCodes=EUR', {resolve: 'body', json: true})
+            .then(body => _.get(body, 'prices.EUR'))
+}
+//end::getMarketPrice[]
+
+//tag::getOffers[]
+function getOffers() {
+    return $http.get('http://localhost:8080/api/v1/offers', {resolve: 'body', json: true}).then(body => body.offers);
+}
+//end::getOffers[]
+
+function notify(offers) {

Aside from the `require()` statements, this was the one other item that wasn't mentioned in the text that I didn't have in my code when I ran the script for the first time. Just FYI.

> @@ -0,0 +1,256 @@
+= Monitoring Bisq offers with Http API
+
+This guide walks you through the process of creating a simple bot that monitors available offers.
+
+
+== What you'll build
+
+You'll build a NodeJS-based script that connects to Bisq over an HTTP API to get offers and market prices and then displays "interesting" offers on the console if any are found.

I think it's officially 'Node.js'. [nitpick]

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/bisq-docs/pull/54#pullrequestreview-133427587
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20180630/8d174a81/attachment-0001.html>


More information about the bisq-github mailing list