-
Notifications
You must be signed in to change notification settings - Fork 0
Exploring the API
The root URI is the entry-point for the Wepow API, and thus the only URI that you need to configure. The production-environment root URI is https://api.wepowapp.com, and the staging-environment root URI is https://api.wopow.co.
In order to authenticate requests, organizations (i.e. Wepow accounts) can issue API keys that grant access to their data through the Wepow. As the Wepow API is stateless, every request should contain the Basic Auth HTTP header with the following credentials:
username: organization_subdomain + "." + user_email
password: api_key
The organization subdomain is used as the identifier, and the user email is used to identify the user for which the requests are made on behalf of. This user email must be the one that the Wepow account is linked to. The API key is the key that the organization should provide to the application that wants to consume the API.
For the sample credentials wepow.developer@wepow.com:50ca32e5a8326c0a3c000001, the resulting header would look as follows:
Authorization: Basic d2Vwb3cuZGV2ZWxvcGVyQHdlcG93LmNvbTo1MGNhMzJlNWE4MzI2YzBhM2MwMDAwMDE=
Along with the Authorization header, the following are also necessary:
Accept: application/hal+json
Content-Type: application/json
For the moment, we are manually setting up test data for parties interested in developing against the API. Please contact us to arrange this.
The API key for the production environment should be configurable by an administrative user of a Wepow organization, as they have the ability to create and manage the organization's keys.
All Wepow environments have a HAL Browser set-up in order to aid development and send requests to the API. The production-environment browser can be found here, and the staging-environment browser can be found here. Everything that can be done with the API can be done through this client, and all the documentation is linked through the docs links. Feel free to use this client as a baseline for your own implementation.
While exploring the API and following the relations in the provided diagram, you might notice that some relations are linked and some are embedded. These are server side optimizations, designed to reduce the number of requests that the clients need to do to achieve the same results. However, this means that a relation that was once a link can arrive in the next request as an embedded object! How do we deal with this?
A linked relation will always point to the full, current representation of a resource.
An embedded relation can be considered a cached representation of a resource. An embedded relation will always have a self link relation, which can be followed to get the latest representation.
When looking for a relation, the process is as follows:
- Look for the relation in the embedded array.
- If not found, look for the relation in the links array, then follow it.