Key Bridge Web Services
Getting Started Guide
Key Bridge Web Services provide web and data services
to power your White Space devices and spectrum-aware applications
and software.
Getting started has never been easier.
Overview & Background
Key Bridge Web Services and developer software provide easy
access many of the core primitives of the Key Bridge White Space System
including registrations, device information, user account interfaces and
more.
If you're building an application that leverages core White Space
System features then this is the API for you.
Key Bridge Web Services are actually multiple APIs
operating on an array of servers and accessing various back-end databases.
Each API interface is developed and presented according to a common access
template and accessed through a standardized REST interface.
Most application developers mix and match components within multiple APIs to produce their application.
All services are authenticated through a common credential system.
Access entitlements are granted via OAuth security credentials.
Some API interfaces are generally available while others require
special access privileges. Review the documentation of each service
to identify any access or entitlement requirements.
The acronym "API" stands for "Application Programming Interface".
An API is a defined way for a program to accomplish a task, usually by
retrieving or modifying data. We provide a API methods for most features
you can see on our White Space Portal. Programmers may use the Key Bridge API
to make applications, web sites, widgets, and other projects that interact
with Key Bridge or that provide spectrum-related functionality.
Programs talk to the API over HTTP, the same protocol that your browser
uses to visit and interact with web pages.
Basic principles of all Key Bridge Web Services are:
- REST
- Access is via HTTP(S) REST
- OAuth
- Authentication is via 2-legged OAuth
- XML & JSON
- All complex data is encoded as XML (default) or JSON
Refer to each service's specific documentation for service-specific
data access, authentication, format & encoding details.
Access via HTTP(S) REST
All Key Bridge Web Services are accessed via HTTP or HTTPS REST transactions.
REST stands for Representational State Transfer and relies on stateless,
client-server, cache-able transactions using the HTTP or HTTPS protocol.
REST is an architecture style for designing networked applications where
simple HTTP messaging is used to make calls between machines rather than
complex mechanisms such as CORBA, RPC or SOAP.
"RESTful" applications use HTTP transactions to read data (e.g., make queries),
write data (e.g. create and/or update), and to delete data. REST uses standard
HTTP transactions for all four standard CRUD (Create/Read/Update/Delete) operations.
All services optionally support HTTPS, while some require HTTPS and do
not support HTTP. Refer to each service's documentation for details.
Key Bridge Web Services employ one or more of the following
HTTP request methods. Check service documentation for more details.
- OPTIONS
- Retrieve information from the server describing which communication options are available.
- GET
- Retrieve information from the server. Query parameters may be encoded in the HTTP request.
- POST
- Submit an update to the server. This is typically used to update an existing database record.
- PUT
- Send new information to the server. This typically used to create a new database record.
- PATCH
- Not used.
- DELETE
- Delete information on the server. This is typically used to delete a database record.
Data Format & Encoding
Key Bridge Web Services read and write data encoded as
XML or JSON, according to the user's configuration.
API services are flexible in this regard, and can mix an match encoding
schemes. For example, a query and response may use different encoding strategies
if desired.
Complex data encoding may be specified by the client by adding a Content-Type
field to the HTTP header. XML is the default context type and is used if no
encoding type is otherwise specified.
- as XML:
Content-Type: application/xml
- as JSON:
Content-Type: application/json
- as XML:
Accept-Encoding: application/xml
- as JSON:
Accept-Encoding: application/json
Developer note
Parameter encoding is important.
All
Key Bridge Web Services require that queries to use the
UTF-8
character set and will always respond using the
UTF-8
character set.
See the
troubleshooting section for details.
Developer note
Collection indexing starts at zero. When iterating through an extended response remember
that the index parameter always starts at 0, not 1.
Starting an index at 1 will skip the first entry in a response collection.
Simple Data
Some services provide simple responses for which object encoding would
not enhance or otherwise benefit the service.
Simple responses are directly provided with the response type text/plain
.
Quotas & Rate Limits
Customer API credentials have no quota or rate limit..
Non-customer access to Key Bridge web services may by capped or rate
limited at our discretion. This is implemented by limited
the number of messages sent to your client based upon volume per
period of time. There are typically two rate limits that may be imposed:
-
A limit on the number of requests per minute. This is to manage the immediate
impact of a single client program that is possibly misconfigured or operating
contrary to our acceptable use policy.
-
A limit on the number of requests per month. This is to manage the long-term
impact and scaling requirements that client applications place upon our
compute and storage infrastructure.
API Keys
All Key Bridge Web Services employ the 2-legged OAuth authentication scheme.
Create an Account
To create an API Key you must first create a system account, which
is managed by the
keybridge:AM
Access Manager system.
Select the New account menu item, enter your email address
and a selected password, then follow the account validation process.
This will establish your individual sign-in credentials (username and password)
that you will use to create and manage your API key(s).
Create an API Key
Select the New API key menu item on the
keybridge:AM
Access Manager system. If you have not already done
so you will be asked to sign in.
Enter a short name for your application ("My First Application" for example)
and optionally a brief description. Leave the operating environment as Development.
Don't worry if you make a mistake - you can edit everything later.
Use an API Key
Key Bridge Web Services authenticate via 2-legged OAuth.
Although there is an official spec for OAuth 1.0, the spec only outlines the standard
"3-legged OAuth". An alternative form, loosely referred to as "2-legged OAuth",
enables secure machine-to-machine communication via a certificate (e.g. username)
and pre-shared keys (e.g. password).
2-legged OAuth is a term that is a variant of OAuth which does not require
users to authenticate through a third-party system. The vast majority of
automated REST API calls made on the Internet using OAuth are made using
2-legged OAuth and allow a device or software to securely and automatically
communicate with a home server.
Key Bridge Web Services access credentials do not have an explicit expiration and will
be valid for use when making requests for as long as your use does not violate
our acceptable use policy.
Configuring OAuth Authentication
Your keybridge:AM issued API key contains two fields:
a Consumer Key
and and Shared Secret
.
Most OAuth clients and software frameworks provide simple configuration interfaces
to enter these configuration parameters.
Configure your 2-legged OAuth client as follows:
Request Signature Configuration
Field |
Description |
Consumer key |
Enter the Consumer Key value exactly as provided.
It's typically easiest and least error-prone to copy and paste directly.
Be sure to not add any spaces!
|
Consumer secret |
Enter the Shared Secret value exactly as provided.
It's typically easiest and least error-prone to copy and paste directly.
Be sure to not add any spaces!
|
Access token |
Leave blank. This is not used. |
Access token secret |
Leave blank. This is not used. |
OAuth Settings Configuration
Field |
Description |
Signature Methods |
HMAC-SHA1 |
OAuth Version |
1.0 |
Realm |
Leave blank. This is not used. If required by the client select Auto and/or Disabled . |
OAuth Nonce |
Leave blank. This is automatically calculated by the client. If required select Auto . |
OAuth Timestamp |
Leave blank. This is automatically provided by the client. If required select Auto . |
Web Service Response Codes
Key Bridge Web Services attempt to return appropriate HTTP status codes for every request.
In addition, a descriptive error text or error message may also be provided in the response
header. The following table describes the codes which typically appear when working with the API:
Code |
Text |
Description |
200 |
OK |
Success! |
400 |
Bad Request |
The request was invalid.
If possible an accompanying error message in the header will explain
the nature of the error encountered.
This status code is typically returned when a required parameter is missing or incorrectly configured.
|
401 |
Unauthorized |
Authentication credentials were missing or incorrect or the request was submitted via HTTP
for a service where HTTPS is required.
|
403 |
Forbidden |
The request is understood, but it has been refused or access is not allowed.
If possible an accompanying error message in the header will explain why.
This code is used when requests are being denied due to over quota or
insufficient access privileges.
|
404 |
Not Found |
The URI requested is invalid or the requested resource, such as database record,
does not exists.
If possible an accompanying error message in the header will provide additional information.
This code is also returned when the requested format is not supported by the requested method.
|
429 |
Too Many Requests |
Returned when a request cannot be served due to the application's rate limit
having been exhausted for the resource.
|
500 |
Internal Server Error |
Something is broken.
Please file a bug report if you see this message so our team can investigate.
|
502 |
Bad Gateway |
The service is not available or being upgraded. |
503 |
Unavailable / Maintenance |
The system is operating but the specific service is either under
maintenance or overloaded with requests.
See the service main page for more information and please try again later.
|
504 |
Gateway timeout |
The system is operating but the request could not be handled
due to a networking failure or misconfiguration. Please try again later.
|
Web Service Troubleshooting
If you are receiving a status code 403: Forbidden
response then your account does not have sufficient privileges
for the resource you are trying to access.
Contact us
to ensure your API credentials are assigned their correct entitlements.
If you are receiving a status code 401: Unauthorized
response then please check the following:
- HTTPS
-
Are you using HTTPS?
Some web service requests must be submitted via HTTPS and not HTTP.
Confirm access requirements with the API's documentation.
- Consumer Key
-
Did you use your public key for a consumer key?
Key Bridge OAuth Consumer keys are formatted as 5 hyphen-separated text fields, as shown in this example:
0724578a-5e7e-11e2-921c-0024211c6fd1
.
- Shared Secret
-
Did you copy the entire shared secret correctly?
The shared secret is a 64-character word and we recommend you copy and paste this sequence instead of transcribing it.
- Character Set
-
Are you submitting or receiving non-standard characters? See below.
UTF-8 Character Set
If you are receiving a status code 400: Bad Request
,
414: Request-URI Too Long
, or 500: Server Error
either intermittently or for requests that should normally work you
may be using an incorrect character set.
Most software uses the system character set by default, which may be US-ASCII
,
LATIN
, etc. To maximize interoperability all Key Bridge Web Services
use and require the the UTF-8
character set when transmitting or
receiving non-standard or international characters.
- as XML:
Content-Type: application/xml;charset=utf-8
- as JSON:
Content-Type: application/json;charset=utf-8
- as XML:
Accept-Encoding: application/xml;charset=utf-8
- as JSON:
Accept-Encoding: application/json;charset=utf-8
Back to top