This article states everything needed to get familiar with the Uberall API, to understand the logic behind it and to make first API calls.
What’s an API?
An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.
Uberall is using a REST API - acronym for REpresentational State Transfer. More information here.
API-Calls (relevant for Uberall API)
GET - to retrieve data/information only – not to modify it in any way
POST - to create new subordinate resources like a location, business, contentlist
PUT - to update existing resource entirely (no creation)
PATCH - to make partial updates on a resource. As you see, PUT requests also modify a resource entity to make it clearer – PATCH method is the correct choice for partially updating an existing resource and PUT should only be used if you’re replacing a resource in its entirety.
DELETE - to delete resources
API-Keys
The uberall API uses 2 API keys to identify your application:
- privateKey - used for server to server communication
- privateKeys should not be shared via Email
- publicKey - used for API calls made from the client’s browser. Limited rights, only usable for the status check
API Keys are specific per client, there is only one privateKey and one publicKey per client.
Please note: Due to security reasons, our Sandbox and Production environments have different API keys.
Your API keys can be found inside the application in the settings section on the bottom left-hand side.
Relevant API-Call URLs
Base URLs
- https://uberall.com/api/ - base url for the live system
- https://sandbox.uberall.com/api/ - base url for the sandbox environment ( testing purposes )
Endpoints
- Locations - https://uberall.com/api/locations
- Businesses - https://uberall.com/api/businesses
- Data Points - https://uberall.com/api/datapoints
- Users - https://uberall.com/api/users
Examples
How to GET a location?
GET call by Location ID
- https://uberall.com/api/locations/123456
- User receives an API-Response with all location data, listings and their status, and other information
GET call by Location’s identifier
- https://uberall.com/api/locations/?identifier=Fahrschule01
- User receives an API-Response with all location data, listings and their status, and other information
- GET Call is the only call to use with location’s identifier
How to create a location via POST?
POST call
- https://uberall.com/api/locations
- User has to define parameters of required data fields to create a location (mandatory fields)
- User receives response Error vs. Success
- Error - information what went wrong is given
- Success - location was created = Location ID in response
How to change location data via PATCH?
PATCH call by Location ID
- https://uberall.com/api/locations/123456
- User has to define parameters of required data fields to create a location (mandatory fields)
- User receives response Error vs. Success
- Error - information what went wrong is given
- Success - location data was changed
How to delete a location via DELETE?
DELETE call by location ID
- https://uberall.com/api/locations/123456
- ACTIVE locations can not be deleted
- Location with billing events can’t be deleted
Errors
DELETE call for active location
ACTIVE locations can not be deleted. Only INACTIVE locations can be deleted, when the location has no current billing event (inactive when start of new month).
Format issue in JSON
Check your JSON and make sure its format is correct - the Uberall system was not able to read it.
Used JSON - can you spot the mistake
Terms to know
API - application programming interface
API-Key - access token, which gives user access to a specific data set
API-Call - a process that takes place when you send a request after setting up your API with the correct endpoints. Your information is transferred, processed, and feedback is returned back.
API-Documentation - technical content deliverable, containing instructions about how to effectively use and integrate with an API. Uberall API-Documentation here
API-Response - response to a request. Can be SUCCESS or ERROR. SUCCESS will also give back the current data of the endpoint. ERROR will give back information regarding the error type.
Endpoint - a point at which an API connects with the software program.
Object Model - list of the objects returned by the endpoints of the API.
Sandbox - testing environment that isolates untested code changes and outright experimentation from the production environment or repository
JSON - (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.
Parsing - interpreting the data with whatever language is used