Hello developers!
In this series I'll be providing you with some explanation and examples on how to work with the bunq SDKs. ๐ First of all it would be good to know that we tried to be consistent across all SDKs, meaning C#, Java, Python and PHP all share the same coding principles.
In this first post I'll demonstrate how to setup the SDK via ApiContext (which was previously done by manually making requests to installation, device-server and session-server) and how to get users belonging to the API key.
This post will also explain how to retrieve attributes from an API deserialised response object.
Alright then, let's get started with ApiContext!
1 .ApiContext
What you need:
Api KeyDevice -descriptionPermitted IPsThe environment you want to use
Create a new ApiContext instance and pass these arguments to it. Doing so will result in the appropriate calls being made to installation, device-server and session-server.
Once the save method has been called, it will save the information such as private key and client pub key to a .conf file. By using this file you can quickly restore your already created ApiContext.
The following code samples will illustrate this in C#, Java, Python and PHP.
Python:
from typing import List
from bunq.sdk import context
def create_api_context(api_key: str, device_description: str,
permitted_ips: List[str]) -> object:
"""
Creates the installation, device-server and session-server and saves
the information to a .conf file. If no file path is given during saving
the default file path is used which is bunq.conf.
:param api_key: Is the apy key that will be used for this context.
:param device_description: The description of the device that is going to be registered.
:param permitted_ips: A list of permitted ips.
:return: The ApiContext object
"""
ctx = context.ApiContext(
context.ApiEnvironmentType.SANDBOX,
api_key,
device_description,
permitted_ips,
)
ctx.save()
return ctx
def restore_api_context():
"""
Restores an already saved ApiContext from the .conf file. If no file path
is given the default file path will be used which is bunq.conf
:return: The ApiContext object
:rtype: object
"""
return context.ApiContext.restore()
PHP:<?php
use bunq\Context\ApiContext;
use bunq\Util\BunqEnumEnvironmentType;
namespace bunq\sdk\examples;
/**
* Creates the installation, device-server and session-server and saves the
* the information to a .conf file. You can pass a file path or use the default
* file name.
*
* @param string $apiKey
* @param string $deviceDescription
* @param string[] $permittedIps
* @return ApiContext
*/
function createApiContext($apiKey, $deviceDescription, array $permittedIps)
{
$apiContext = new ApiContext(BunqEnumEnvironmentType::SANDBOX(), $apiKey, $deviceDescription,
$permittedIps);
$apiContext->save(ApiContext::DEFAULT_FILENAME_CONFIG);
return $apiContext;
}
/**
* Resotres an already saved ApiContext from the .conf file. If the default
* file path has been used remember to use it again.
*
* @return ApiContext
*/
function restoreApiContext()
{
return ApiContext::restore(ApiContext::DEFAULT_FILENAME_CONFIG);
}
Java:package com.bunq.sdk.examples;
import com.bunq.sdk.context.ApiContext;
import com.bunq.sdk.context.ApiEnvironmentType;
import java.util.List;
/**
* Create an API context or restore an already made ApiContext.
*/
public class ApiContextSaveExample {
/**
* Creates the installation, device-server and sessoin-server and saves the inforation to a .conf
* file. If no file path is given when saving the default file path will be used which is
* bunq.conf
*
* @param apiKey Is the apy key that will be used for this context.
* @param deviceDescription The description of the device that is going to be registered.
* @param permitted_ips A list of permitted ips.
* @return The newly created ApiContext that is going to be used to make api calls.
*/
public static ApiContext createApiContext(String apiKey, String deviceDescription,
List<String> permitted_ips) {
ApiContext context = new ApiContext(ApiEnvironmentType.SANDBOX, apiKey, deviceDescription,
permitted_ips);
context.save();
return context;
}
/**
* Restore an already saved ApiContext. If no file path is specified than the deffault file
* path is used which is bunq.conf
*
* @return The restored API context from a .conf file
*/
public static ApiContext restoreApiContext() {
return ApiContext.restore();
}
}
C#using System.Collections.Generic;
using Bunq.Sdk.Context;
using Bunq.Sdk.Samples.Utils;
namespace Bunq.Sdk.Samples
{
public class ApiContextSample
{
/// <summary>
/// Creates the installation, device-server and session-server and save the information to a .conf
/// file. If no file path is given during saving he default file path is used which is bunq.conf.
/// </summary>
/// <param name="apiKey"> Is the apy key that will be used for this context.</param>
/// <param name="deviceDescription">The description of the device that is going to be registered.</param>
/// <param name="permittedIps">A list of permitted ips.</param>
static ApiContext CreateNewApiContext(string apiKey, string deviceDescription, IList<string> permittedIps)
{
var apiContext = new ApiContext(ApiEnvironmentType.SANDBOX, apiKey, deviceDescription, permittedIps);
apiContext.save();
return apiContext;
}
/// <summary>
/// Restore an already saved ApiContext from the .conf file. If no file path is given the default file
/// path will be used which is bunq.conf.
///</summary>
static ApiContext ResotreApiContext()
{
var apiContext = ApiContext.Restore();
return apiContext;
}
}
}
2. User
What you need:
ApiContextUser id (optional)
User will make a call to the user endpoint, this will return a deserialised User object. Via this object you can get all the response values you need.
The following code samples will demonstrate hot to retrieve attributes from a User object in C#, Java, Python and PHP.
Python:
from bunq.sdk.context import ApiContext
from bunq.sdk.model.generated import endpoint
INDEX = 0
USER_ID = 50
def get_user(api_context: ApiContext, user_id=None) -> object:
"""
Get all users or a specific user beloging to the api key.
:param api_context: The ApiContext instance.
:param user_id: The user id of the specific user.
:type api_context: bunq.sdk.context.ApiContext
:type user_id: int
"""
if user_id is None:
# get all the users
return endpoint.User.list(apicontext=api_context)[INDEX]
else:
# get a specific user
return endpoint.User.get(api_context=api_context, user_id=user_id)
# if the user is a UserCompany
company = get_user(api_context, USER_ID).UserCompany
# if the user is a UserPerson
person = get_user(api_context, USER_ID).UserPerson
# the examples below apply to both person and company
# get the public nickname -> str
person.public_nick_name
# get the length of this session in seconds -> int
person.session_timeout
# get avatar uuid for this user -> str
person.avatar.uuid
# get the public attachemt uuid of this avatar -> str
person.avatar.image[INDEX].attachment_public_uuid
# get the date of birth of the user -> str
person.date_of_birth
# get the user id -> int
preson.id_
PHP:<?php
namespace bunq\sdk\examples;
use bunq\Context\ApiContext;
use bunq\Model\Generated\User;
const INDEX = 0;
const USER_ID = 50;
/**
* @param ApiContext $apiContext
* @param int $userId
*
* @return User
*/
function getUser(ApiContext $apiCntext, $userId = null)
{
if ($userId == null) {
// Get all the users
return User.listing($apicontext);
} else {
// Get a speific user
return User.get($apiContext, $userId);
}
}
// If the user is a userCompany
$company = getUser($apiContext, USER_ID)->getUserCompany();
// If the user is a userPerson
$person = getUser($apiContext, USER_ID)->getUserPerson();
// The examples below work both with person and company
// get the public nickname -> string
$person->getPublicNickName();
// Get the lenght of this session in seconds -> int
$person->getSessionTimeout();
// Get the avatar uuid -> string
$person->getAvatar()->getUuid();
// Get the pulbic attachment of this avatar -> string
$person->getAvatar()->getImage()[INDEX]->getAttachmentPublicUuid();
// Get the date of birth of the user -> string
$person->getDateOfBirth();
// Get the user id -> int
$person->getId();
Java:package com.bunq.sdk.examples;
import com.bunq.sdk.context.ApiContext;
import com.bunq.sdk.model.generated.User;
import com.bunq.sdk.model.generated.UserCompany;
import com.bunq.sdk.model.generated.UserPerson;
int USER_ID = 50;
int INDEX = 0;
ApiContext API_CONTEXT = ApiContext.restore();
public class GetUsersExample {
/**
* Returns a User wrapper object given a user id.
*/
public static User getUser(ApiContext apiContext, int userId) {
return User.get(apiContext, userId);
}
/**
* Get a list of all the users belonging to this api key.
*/
public static List<User> getAllUsers (ApiContext apiContext) {
return User.list(apiContext);
}
}
// Use this line if your user is UserCompany
UserCompany company = GetUsersExample.getUser(API_CONTEXT, USER_ID).getUserCompany();
// Use this line if your user is UserPerson
UserPerson person = GetUsersExample.getUser(API_CONTEXT, USER_ID).getUserPerson();
// The following examples work for both person and company
// Get the public nickname -> String
person.getPublicNickName();
// Get the length of this session in seconds -> int
person.getSessionTimeout();
// Get the avatar uuid for this user -> String
person.getAvatar().getUuid();
// Get the public attachment uuid for this usser -> String
person.getAvatar().getImage().get(INDEX).getAttachmentPublicUuid()
// Get the date of birth of the user -> String
person.getDateOfBirth()
// Get the user id -> int
person.getId()
C#:using Bunq.Sdk.Context;
using Bunq.Sdk.Model.Generated;
namespace Bunq.Sdk.Samples
{
public class GetUserExmaple
{
static int INDEX = 5;
static int USER_ID = 5;
/// <summary>
/// Get a user by its ID.
/// </summary>
static User GetUser(ApiContext apiContext, int userId)
{
// Get a specific user
return User.Get(apiContext, userId);
}
/// <summary>
/// Get all users or a specific user belonging to this api key.
/// </summary>
static IList<User> GetAllUsers(ApiContext apiContext)
{
// Get all the users
return User.list(apicontext)[INDEX];
}
}
}
// Use this line if your user is UserCompany
UserCompany company = GetUser(apiContext, USER_ID).UserCompany;
// Use this line if your user is UserPerson
UserPerson person = GetUser(apiContext, USER_ID).UserPerson;
// The examples below apply to both person and company
// Get the public nickname -> string
person.PublicNickName;
// Get the lenght of this sessoin is seconds -> int
person.SessionTimeout;
// Get avatar uuid for this user -> string
person.Avatar.Uuid;
// Get the public attacment uuid for this avatar -> string
person.Avatar.Image[INDEX].AttachmentPublicUuid;
// Get the date of birth for the user -> string
person.DateOfBirth;
// Get the user id -> int
person.Id;
Let me know which examples you would like to see next!
Happy coding!