Skip to content

Commit

Permalink
Merge pull request #84 from bunq/update_read_me_bunq/sdk_java#81
Browse files Browse the repository at this point in the history 
Updated read me to point to tinker for examples. (#81)
  • Loading branch information
@OGKevin
OGKevin authored May 9, 2018
2 parents 546ed01 + 7cdf35b commit 72e26b8
Showing 1 changed file with 31 additions and 81 deletions.
112 changes: 31 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,138 +36,88 @@ ApiContext apiContext = ApiContext.create(ENVIRONMENT_TYPE, API_KEY,
apiContext.save(API_CONTEXT_FILE_PATH);
```

**Please note:** initializing your application is a heavy task and it is recommended to do it only once per device.
**Please note:** <u>initialising your application is a heavy task and it is recommended to do it only once per device.</u>

After saving the context, you can restore it at any time:

```
ApiContext apiContext = ApiContext.restore(API_CONTEXT_FILE_PATH);
BunqContext.loadApiContext(apiContext);
```

**Tip:** both saving and restoring the context can be done without any arguments. In this case the context will be saved
to/restored from the `bunq.conf` file in the same folder with your executable.
**Tip:** both saving and restoring the context can be done without any arguments. In this case the context will be saved to/restored from the `bunq.conf` file in the same folder with your executable.

#### Example
See [`ApiContextSaveExample.java`](./src/main/java/com/bunq/sdk/examples/ApiContextSaveExample.java)

The API context can then be saved with:
See [`tinker/load_api_context`](https://github.com/bunq/tinker_java/blob/b03cbc2b84f35de9721a4083843c4015665d67f8/src/main/java/com/bunq/tinker/libs/BunqLib.java#L96-L101)

#### Safety considerations
The file storing the context details (i.e. `bunq.conf`) is a key to your account. Anyone having
access to it is able to perform any Public API actions with your account. Therefore, we recommend
choosing a truly safe place to store it.

### Making API calls
There is a class for each endpoint. Each class has functions for each supported action. These
actions can be `create`, `get`, `update`, `delete` and `list`.
There is a class for each endpoint. Each class has functions for each supported action. These actions can be `create`, `get`, `update`, `delete` and `list`.

When making calls, The `userId` and `monetaryAccountId` needed to make calls will be determined by the SDK it. When no `monetaryAccountId` has been passed, the SDK will use the first active monetary account it can find. This is normally the monetary account used for billing.

Sometimes API calls have dependencies, for instance `MonetaryAccount`. Making changes to a monetary
account always also needs a reference to a `User`. These dependencies are required as arguments when
performing API calls. Take a look at [doc.bunq.com](https://doc.bunq.com) for the full
documentation.
Before you make a call, make sure that you have loaded `ApiContext` in to the `BunqContext`.

#### Creating objects
Creating objects through the API requires an `ApiContext`, a `requestMap` and identifiers of all
dependencies (such as User ID required for accessing a Monetary Account). Optionally, custom headers
can be passed to requests.
With the `create` method you can create new models. This method normally returns the `id` of the created model.


```
Map<String, Object> paymentMap = new HashMap<>();
Amount paymentAmount = new Amount(PAYMENT_AMOUNT, PAYMENT_CURRENCY);
paymentMap.put(Payment.FIELD_AMOUNT, paymentAmount);
Pointer pointerCounterparty = new Pointer(COUNTERPARTY_POINTER_TYPE, COUNTERPARTY_EMAIL);
paymentMap.put(Payment.FIELD_COUNTERPARTY_ALIAS, pointerCounterparty);
paymentMap.put(Payment.FIELD_DESCRIPTION, PAYMENT_DESCRIPTION);
Integer paymentId = Payment.create(
apiContext,
generateExamplePaymentMap(),
USER_ITEM_ID,
MONETARY_ACCOUNT_ITEM_ID
Payment.create(
new Amount(amount, CURRENCY_EURO),
new Pointer(POINTER_TYPE_EMAIL, recipient),
description
);
```

##### Example
See [`PaymentExample.java`](./src/main/java/com/bunq/sdk/examples/PaymentExample.java)
See [`tinker/make_payment`](https://github.com/bunq/tinker_java/blob/cc41ff072d01e61b44bb53169edb80bde9620dc5/src/main/java/com/bunq/tinker/MakePayment.java#L46)

#### Reading objects
Reading objects through the API requires an `ApiContext`, identifiers of all dependencies (such as
User ID required for accessing a Monetary Account), and the identifier of the object to read (ID or
UUID) Optionally, custom headers can be passed to requests.

This type of calls always returns a model.
Reading objects can be done via the `get` or `list` method.

These type of calls always returns the model or binary data.

```
MonetaryAccount monetaryAccount = MonetaryAccount.get(
apiContext,
USER_ITEM_ID,
MONETARY_ACCOUNT_ITEM_ID
);
Payment.list(
monetaryAccountBank.getId(),
pagination.getUrlParamsCountOnly()
)
```

##### Example
See [`MonetaryAccountExample.java`](./src/main/java/com/bunq/sdk/examples/MonetaryAccountExample.java)
See [`tinker/get_all_payment`](https://github.com/bunq/tinker_java/blob/b03cbc2b84f35de9721a4083843c4015665d67f8/src/main/java/com/bunq/tinker/libs/BunqLib.java#L161-L164)

#### Updating objects
Updating objects through the API goes the same way as creating objects, except that also the object to update identifier
(ID or UUID) is needed.
Updating objects through the API goes the same way as creating objects, except that also the object to update identifier (ID or UUID) is needed.

The `update` method will also normally return the `Id` of the updated model.

```
Map<String, Object> requestMapUpdate = new HashMap<>();
requestMapUpdate.put(RequestInquiry.FIELD_STATUS, STATUS_REVOKED);
RequestInquiry.update(
apiContext,
requestMapUpdate,
USER_ITEM_ID,
MONETARY_ACCOUNT_ITEM_ID,
REQUEST_ID
);
MonetaryAccountBank.update(Integer.parseInt(accountId), name);
```

##### Example
See [`RequestExample.java`](./src/main/java/com/bunq/sdk/examples/RequestExample.java)
See [`tinker/update_monetary_account`](https://github.com/bunq/tinker_java/blob/b03cbc2b84f35de9721a4083843c4015665d67f8/src/main/java/com/bunq/tinker/UpdateAccount.java#L36)

#### Deleting objects
Deleting objects through the API requires an `ApiContext`, identifiers of all dependencies (such as User ID required for
accessing a Monetary Account), and the identifier of the object to delete (ID or UUID) Optionally, custom headers can be
passed to requests.

```
CustomerStatementExport.delete(apiContext, userId, monetaryAccountId, customerStatementId);
```

##### Example
See [`CustomerStatementExportExample.java`](./src/main/java/com/bunq/sdk/examples/CustomerStatementExportExample.java)
Deleting object can be done via the `delete` method. This method also requires the object identifier which could be an `Id` or `uuid`.

#### Listing objects
Listing objects through the API requires an `ApiContext` and identifiers of all dependencies (such as User ID required
for accessing a Monetary Account). Optionally, custom headers can be passed to requests.
This method normally returns an empty response.

```
List<User> users = User.list(apiContext);
CustomerStatementExport.delete(customerStatementId);
```

##### Example
See [`UserListExample.java`](./src/main/java/com/bunq/sdk/examples/UserListExample.java)

## Running Examples
In order to make the experience of getting into bunq Java SDK smoother, we
have bundled it with example use cases (located under `./src/main/java/com/bunq/sdk/examples/`).

To run an example, please do the following:
1. In your IDE, open the example you are interested in and adjust the constants,
such as `API_KEY` or `USER_ID`, to hold your data.
2. Since Java IDE's are typically advanced just run the example of your choice in your IDE.

In order for examples to run, you would need a valid context file (`bunq.conf`)
to be present in the bunq SDK project root directory. The file can either copied
from somewhere else (e.g. tests) or created by executing the `ApiContextSaveExample.java` in your
IDE.

Please do not forget to set the `API_KEY` constant in `ApiContextSaveExample.java` to your actual
API key before running the example!
To have an idea on how the SDK works you can play around with the java tinker located at: https://github.com/bunq/tinker_java

## Running tests
Information regarding the test cases can be found in the [README.md](./src/test/README.md)
Expand Down

0 comments on commit 72e26b8

Please sign in to comment.