Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Getting started with APIs v.3 #1591

Merged
merged 3 commits into from
Oct 6, 2023
Merged

Getting started with APIs v.3 #1591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5b2c1d2
Make API start text more sequential
halvorsanden Sep 1, 2023
e912d00
Add figures to getting started
halvorsanden Oct 5, 2023
2aff2a9
Remove trailing slash from tracking api
halvorsanden Oct 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 168 additions & 113 deletions content/api/_index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,133 +11,188 @@
- api/api.html
---

<section class="dev-docscontent__section">
<img src="./api-model.png" class="maxw50r mbm" alt="" />

<section class="dev-docscontent__section" aria-label="Connecting to the APIs">
<p class="text-heading fw600 mbl">
Authentication is required by all APIs, that means having a Mybring user
account with an API key. Authorisation is required by some APIs, that means
having a customer number and certain rights connected to the user. The
following describes how the requirements work together and how to obtain
them.
All API connections require <em>authentication</em> via a Mybring user
account with an API key. Some APIs also require <em>authorisation</em> to
identify the Bring customer. The following describes how the requirements
work together and how to fill them before connecting.
</p>

<h2 class="dev-anchored" id="api-customer-number">Customer number</h2>
<p>
In order to use the majority of our APIs, your company needs to be a Bring
customer and have a customer number. While most customers have only one
customer number, many also choose to have multiple when they need to separate
departments or subsidiaries.
</p>
<p>
If the API you want to use requires a customer number and you don’t have one
yet, contact customer support via your country’s Bring site.
</p>
<p>
If you need a customer number for testing purposes, it can be found in the
<a href='{{< relref "testing" >}}'>API testing documentation</a>.
</p>
<h2 class="dev-anchored" id="user">1. User account</h2>
<div class="startguide-item">
<div>
<p>
If you don’t have a user already,
<a href="https://www.mybring.com/signup/register/user"
>register a new account</a
>.
</p>
<p>
Some like to have an account dedicated to API use, but it depends on you
or your company’s needs. The account type is no different either way.
</p>
<p>
When you have a Mybring user account, you must create an API key and
give the user access to the customer number you want to make action on
behalf of.
</p>
</div>
<figure>
<img
src="/images/getting-started/user.png"
alt="Two inputs, a button and a user icon to signigy user account."
/>
<figcaption>Register a user account in Mybring.</figcaption>
</figure>
</div>
<h2 class="dev-anchored" id="api-key">2. API key</h2>
<div class="startguide-item">
<div>
<p>
The API key is created and managed on the
<a href="https://www.mybring.com/useradmin/account/settings/api"
>Mybring API page</a
>.
</p>
<p>
The key is, like a password, unique to your user account. It’s used with
the user account email address when connecting to the APIs.
</p>
<p class="message--warn pam">
If you change or delete the API key or delete the entire user account,
any integration using it will stop working and must be updated with a
new key.
</p>
</div>
<figure>
<img
src="/images/getting-started/key.png"
alt="A masked string and characters, a button and a key icon."
/>
<figcaption>
Create and manage an API key for the user account.
</figcaption>
</figure>
</div>

<h2 class="dev-anchored" id="user">Mybring user account</h2>
<p>
You need a personal Mybring user account to work with the Bring API’s. If
you don’t have one already,
<a href="https://www.mybring.com/signup/register/user"
>register a new account</a
>.
</p>
<h2 class="dev-anchored" id="api-customer-number">3. Customer number</h2>
<div class="startguide-item">
<div>
<p>
Your company or organisation needs to be a Bring customer and have a
customer number to use the majority of our APIs. Requests use the number
to identify, for instance, who to invoice or provide information about.
</p>
<p>
If the API you want to use requires a customer number and the company or
organisation doesn’t have one yet, contact customer support via your
country’s Bring site.
</p>
<p>
A customer number for testing purposes can be found in the
<a href='{{< relref "testing" >}}'>API testing documentation</a>.
</p>

<h3 class="dev-anchored" id="access">Customer number access</h3>
<p>
You can see the customer numbers your account has access to on the
<a href="https://www.mybring.com/useradmin/account/settings/api"
>Mybring API page</a
>. If the customer number you are looking for isn’t listed, you can get
access to it through one of the following methods:
</p>
<ul>
<li>
Go to
<a href="https://www.mybring.com/useradmin/account/settings"
>Customer numbers and rights in Mybring</a
>, search for the customer number and apply for access.
</li>
<li>
Contact your customer’s administrator and get them to connect your user.
</li>
</ul>
<p>
You might work with multiple companies and each of these companies might
have multiple customer numbers in Bring. You can use the same Mybring user
for different companies.
</p>
<h3 class="dev-anchored" id="access">User, number and rights</h3>
<p>
The user account makes API requests for customer numbers it has access
to. Rights control what the user can do within a customer number, for
instance, placing orders or accessing financial information.
</p>
<p>
You can see the accesses on the
<a href="https://www.mybring.com/useradmin/account/settings/api"
>Mybring API page</a
>. If the customer number you are looking for isn’t listed, you can get
access to it and acquire the necessary rights through one of the
following methods:
</p>
<ul>
<li>
Go to
<a href="https://www.mybring.com/useradmin/account/settings"
>Customer numbers and rights in Mybring</a
>, search for the customer number and apply for access and rights.
</li>
<li>
Contact your administrator and get them to connect your user to the
customer number and set the rights.
</li>
<li>
If you are an administrator, users access and rights to customer
numbers can be managed in
<a href="https://www.mybring.com/useradmin-external/users"
>Mybring’s user administration</a
>.
</li>
</ul>
<p class="message--info pam">
Most companies have only one customer number, and most users have access
to only one customer number. Still, having multiple numbers and accesses
is possible. Rights are specific to each customer number.
</p>
</div>
<figure>
<img
src="/images/getting-started/customer.png"
alt="Office building with number, underneath is a user with icons representing rights to ordering, financial data, reports and price calculation."
/>
<figcaption>
Companies have customer numbers. The user account is given certain
rights within a customer number to make corresponding requests.
</figcaption>
</figure>
</div>

<h3 class="dev-anchored" id="rights">User rights</h3>
<p>
Rights control what the user can do, for instance order certain services on
behalf of the company or see certain information about it. While one user
can have access to many different customers, the rights are specific for
each customer number. The company administrator manages these within the
company and the user can apply for
<a href="https://www.mybring.com/useradmin/account/settings"
>customer numbers and rights in Mybring</a
>.
</p>

<h3 class="dev-anchored" id="api-key">API Key</h3>
<p>
When you have a Mybring user, you can create an API key. The key is
necessary for authentication and is unique to your user account. It’s used
together with the user account email address when connecting to the APIs.
The same key is used for all APIs and all Bring customer numbers the user
has access to.
</p>
<p>
Be aware that if you choose to change or delete the API key or delete the
entire user account, any integration using it will stop working and must be
updated with a new key.
</p>
<p>
The API key is created and managed in the
<a href="https://www.mybring.com/useradmin/account/settings/api"
>Mybring API page</a
>.
</p>
<h2 class="dev-anchored" id="connecting">4. Connect to the APIs</h2>
<div class="startguide-item">
<div>
<p>
When you have the user account and the API key, you can connect to the
APIs through your system or an API client. Each API has additional
details about individual requirements and procedures, but the following
three HTTP header parameters are always required.
</p>
<h3 class="dev-anchored" id="authentication">Authentication headers</h3>
<dl class="bg-gray2 rad-a2px pal maxw50r">
<dt>X-Mybring-API-Uid</dt>
<dd>The email address of your Mybring user account.</dd>
<dd class="mbm">Example: <code>name@your-company-domain.com</code></dd>

<h2 class="dev-anchored" id="authentication">Authentication headers</h2>
<p>
When you have the user account with the access, rights and API key, you are
ready to connect to the APIs in either your own system or an API client.
Each API has individual details, but the following three HTTP header
parameters are always required.
</p>
<dl class="bg-gray2 rad-a2px pal maxw50r">
<dt>X-Mybring-API-Uid</dt>
<dd>The email address of your Mybring user account.</dd>
<dd class="mbm">Example: <code>name@your-company-domain.com</code></dd>

<dt>X-Mybring-API-Key</dt>
<dd>The user account’s API key.</dd>
<dd class="mbm">
Example: <code>1234abc-abcd-1234-5678-abcd1234abcd</code>
</dd>
<dt>X-Mybring-API-Key</dt>
<dd>The user account’s API key.</dd>
<dd class="mbm">
Example: <code>1234abc-abcd-1234-5678-abcd1234abcd</code>
</dd>

<dt>X-Bring-Client-URL</dt>
<dd>The URL for the service where you are using the API.</dd>
<dd>Example: <code>your-company-domain.com</code></dd>
</dl>
<dt>X-Bring-Client-URL</dt>
<dd>The URL for the service where you are using the API.</dd>
<dd>Example: <code>your-company-domain.com</code></dd>
</dl>
</div>
<figure>
<img
src="/images/getting-started/integration.png"
alt="A group of credential icons with an arrow pointing to a terminal, annother arrow is pointing out from the terminal to a group of icons representing the different data types."
/>
<figcaption>
All the prerequisites are used to make a request. The requests evaluate
if the user account has the correct rights within the customer number
before returning a response.
</figcaption>
</figure>
</div>
</section>

<section class="dev-docscontent__section">
<section class="dev-docscontent__section" aria-label="Keeping up to date">
<h2 class="dev-anchored" id="status-and-support">
Updates, status and support
</h2>
<p>
Stay up to date on changes and new features by subscribing to
<a
href='{{< relref "revision-history">}}'
>API updates</a
>. You can subscribe to all or pick the areas relevant to you.
<a href='{{< relref "revision-history">}}'>API updates</a>. You can
subscribe to all or pick the areas relevant to you.
</p>
<p>
We continuously monitor our APIs with health checks to measure uptime.
Expand All @@ -155,7 +210,7 @@ <h2 class="dev-anchored" id="status-and-support">
</p>
</section>

<section class="dev-docscontent__section">
<section class="dev-docscontent__section" aria-label="API formats">
<h2 class="dev-anchored" id="formats">Formats</h2>
<p>
All our APIs are REST APIs supporting JSON and XML.
Expand Down
Binary file removed content/api/api-model.png
View file
Open in desktop
Binary file not shown.
2 changes: 1 addition & 1 deletion content/api/tracking/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,6 @@ documentation:
| tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |


oas: https://api.bring.com/tracking/api-docs/
oas: https://api.bring.com/tracking/api-docs

---
5 changes: 5 additions & 0 deletions css/base.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,3 +120,8 @@ ol {
list-style-type: decimal;
margin-left: 1.6em;
}

figcaption {
font-size: 0.83rem;
margin-top: 0.5rem;
}
22 changes: 22 additions & 0 deletions css/documentation.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,28 @@ p a:not(.btn-link--dark, .btn-link) {
grid-area: signup;
}

.startguide-item {
display: flex;
flex-flow: row wrap;
align-items: flex-start;
gap: 2rem;
max-width: max-content;
padding-bottom: 1rem;
margin-bottom: 3rem;

& > div {
flex: 1 2 24rem;
max-width: 34rem;
}

& > figure {
flex: 1 1 12rem;
max-width: 16rem;
position: sticky;
top: 6rem;
}
}

.dev-docs__menu {
background-color: var(--gray-93);
display: flex;
Expand Down
Binary file added static/images/getting-started/customer.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/getting-started/integration.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/getting-started/key.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/images/getting-started/user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading