API

Basics

Getting an API client

You will need a client id and a client secret to use the RamBase API. Contact us to get these. Send us a short description of what the API client is supposed to do, and the API resources you want to request. Based on this information, we create an API client with the correct authentication flow and permissions for the necessary API resources. Do not share the client secret with anyone under any circumstances.

Getting an access token

When you receive your client id and client secret you should authorize using the right authentication flow. If successful, login gives you an access token in return, along with an expire time in seconds. Keep your access token secret and don't share it with anyone.

REST basics

Now that you have the access token you are ready to make a request to the RamBase REST API. REST is acronym for REpresentational State Transfer, an architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his famous dissertation. All information in the RamBase API, like sales orders, employees and products, are created, read, updated and deleted by API resources. The following HTTP methods/verbs are supported:

  • GET: Used to retrieve a representation of the API resource.
  • PUT: Used to update the API resource with the state given in the request body. Note that only the parts provided are updated. RamBase API does not support the use of the PATCH method.
  • POST: Used to create new API resources. The response usually contains a representation of the newly created API resource.
  • DELETE: Used to delete API resources. Subsequent GET requests on the deleted API resource are expected to return HTTP status 404.

The GET method is safe, meaning that applying it to a resource does not result in a state change of the resource. The GET, PUT and DELETE methods are idempotent, meaning that applying any of these method multiple times to a resource results in the same state change as applying them once.

RamBase REST API is stateless. Every API request contains all the information necessary to understand the request and cannot take advantage of any stored context on the server. Session state is maintained entirely on the client side.

All of our API resources can be found in the REST APIs section and the special APIs section.

Making requests

The RamBase REST API only covers parts of the RamBase service. We are continuously working to expose new functionality. If you find our API lacking information to complete your integration, please contact us!

In this example we want to make a request to retrieve information about the sales order API resource with the identifier 123456. We use the GET method to request the URI https://api.rambase.net/sales/orders/123456.

You can specify the format of the response by setting the query parameter $format to json or xml. In this case the URI https://api.rambase.net/sales/orders/123456?$format=json.

The following response formats are supported:

  • JSON (recommended): Example $format=json
  • JSON stream: Example $format=jsonstream (only supported for some API resources)
  • XML: Example $format=xml
  • HTML: Example $format=html
The format of the request body cannot be specified the same way as response format, but both XML and JSON is allowed.

The access token can be provided by using one of the following:

  • HTTP request header (recommended): The Authorization request header with the value Bearer ACCESS_TOKEN
  • Query parameter: You can add the query parameter $access_token=ACCESS_TOKEN to the request URI.

If your API request returns a HTTP 403 (Forbidden), the causes might be as follows:

  • Access token is missing: Make sure the access token was provided as a HTTP request header or as a query parameter.
  • Access token has expired: Prompt the user for authorization to get a new access token. Some API clients also allow the use of a refresh token to obtain a new access token.
  • API client does not have access to the API resource: Contact us to get access to the specific API resource
  • Authenticated user is missing permission: Contact the role administrator owning the RamBase data to give the user the right role or duty to make the request.
  • Other: The business logic does not allow the current user to perform the request. Read the error response for more details.

Further reading

Now that you are able to make requests to our API you can start digging into the details of our API:

  • Only a limited set of data types are used in our API.
  • Our API offers a range of query parameters to enable/disable features and enrichens the result.
  • When making GET requests to retrieve a list of objects you can usually sort and/or filter the result.
  • Some API resources can include more data in the response by using the expand query parameter.
  • Limit the data when retrieving API resources by using the select query parameter.
  • All of the error messages returned from the RamBase REST API follow the same structure.
  • RamBase customers can add custom fields to objects like products and sales orders. These custom fields are also included in our API resources.
  • Some of the fields used in our API resources have a limited set of domain values that can be provided.
  • When actions are performed on API resources, like forward, register, calculations etc., we use the concept of API operations. An instance is added for each time the API operation is triggered.
  • Sometimes, but not often, our APIs become obselete and need to be updated. In our API we have tried to make the handling of deprecated API resources as easy as possible.
  • Webhooks allow you to build or set up applications which subscribe to certain events in RamBase. When one of those events is triggered, we send a HTTP POST payload to the webhook's configured URL.
  • If you are developing using C#, make sure to check out our open source C# SDK.