Getting Started Guide

keybridge:API provide web and data services to power your White Space devices and spectrum-aware applications and software.

Getting started has never been easier.

Overview

keybridge:API managed 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.

keybridge:API managed 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.

Background

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 keybridge:API services are:

  1. Access is via HTTP or HTTPS REST, depending upon the service
  2. Authentication is via 2-legged OAuth
  3. The data model is WSIF with XML or JSON encoding

Refer to each service's specific documentation for that service's root URI.

Access via HTTP(S) REST

All keybridge:API 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.

keybridge:API 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 Model

keybridge:API services exchange data using the Wireless Service Information Format (WSIF), an open, standard data formatting strategy supporting the encoding and communication of wireless service descriptions.

WSIF accommodates all wireless services described within the White Space Rules including licensed and unlicensed services. It is sufficiently generalized to also describe many other types wireless operation including microwave, satellite, cellular, etc. WSIF supports:

  • Generalized descriptions of wireless transmitters and receivers
  • Standardized Geo-location information format
  • Cross-domain spectrum administration and frequency coordination
  • Network planning and wireless service coexistence information
  • Transparent, open implementation of White Space administration

The White Space Information Format (WSIF) is an information-formatting scheme that enables consistent presentation, validation, persistence and exchange of wireless service descriptions and technical operating details. The WSIF specification provides a data modeling framework within which the characteristics of any conventional wireless service may be described. WSIF accommodates all known White Space service identification requirements.

WSIF is based upon and extends the MCEB Pub 8 Standard Spectrum Resource Format (v3) to accommodate White Space and other commercial implementation requirements and to enable consistent presentation, validation, persistence and exchange of wireless service descriptions and technical operating details. It accommodates worldwide White Space service requirements and is sufficiently generalized to also describe many other types of wireless operation including microwave, satellite, cellular, etc.

The WSIF specification defines the following core object entities, along with a number of enumerated objects and values defined in the appendices.

Name Object Model Description
Address Describes a physical mailing address.
Antenna Container for antenna profile and directional gain information. An Antenna is associated with and assigned to a Device.
Channel A fully qualified and unique frequency range. Channel may be used to describe any discrete frequency range and indicates the regulatory authority from which it is defined.
Contact Describes a point of contact. A Contact includes an Address.
Coordinate Standard container for geographical location (position) information.
Device An abstract description of general radio transmitter and receivers. A generic and set of service-specific implementations are also defined.
License Generalized container for Government issued transmission licenses and call signs.
Location A generalized container for geographical location information. A Location encompasses a related Address, Coordinate and Geometry instance.
Schedule A database and software developer-friendly iCalendar / vEvent representation.
Station Describes a physical facility where a transmitter or receiver may be located. A station contains a schedule, one or more Devices, and a Location.
Wireless Service A generalized wireless service description. A Wireless Service includes one or more Stations, a License, one or more Contacts, and one or more Whitespace Registrations.
Whitespace Registration Describes a White Space registration that is entitled to receive protection.

WSIF supports the description of various types of wireless services through configuration of the indicated attributes and elements. An important and required attribute for WSIF implementation is the wirelessServiceType, which uniquely identifies the wireless service and is used to determine which and how many elements and attributes are required within the WSIF wirelessService object description.

WSIF also includes several data objects designed specifically to support White Space information query and the efficient and thorough description of available channel information.

Name REST Query & Response Description
Whitespace Query A Rules-compliant query definition that may be submitted by a client White Space device to a White Space administrator to receive White Space spectrum availability information.
Whitespace Response A Rules-compliant response definition that may be sent from a White Space administrator to a White Space device in response to provide spectrum availability information.
Whitespace Frequency A fully qualified and Rules-compliant definition of White Space spectrum availability information.

Data Encoding

keybridge:API 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.

Data encoding is specified by the client by adding a Content-Type field to the HTTP header with the following parameter:

  • 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 keybridge:API 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
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 over skip the first set of response values.

API Keys

We recommend you thoroughly review the documentation to better understand the operating principles and requirements for interacting with keybridge:API services. For experienced developers we offer the following summary.

  1. All services are accessed via HTTP or HTTPS REST
  2. Authentication is via 2-legged OAuth
  3. The data model is WSIF with XML or JSON encoding

Get an API key

All keybridge:API web and data services employ the 2-legged OAuth authentication scheme.

Don't know where to start? Follow these easy steps and you will not get lost.

1) 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).

2) 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.

Using API keys

keybridge:API 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.

keybridge:API 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.

keybridge:API services accessed using non-customer API credentials may cap 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:

  1. 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.
  2. 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.

Customer API credentials have no caps.

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. Configure your OAuth client as follows:

Field Description
Consumer key Enter the Consumer Key value exactly as provided by keybridge:AM. 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 by keybridge:AM. Again, 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.
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".

Response Codes

keybridge:API 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 may 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 why. This status code is typically returned when a PUT parameter is incorrectly configured.
401 Unauthorized Authentication credentials were missing or incorrect or the request was submitted via HTTP and not HTTPS.
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 keybridge:API 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 keybridge:API system is operating but the request could not be handled due to a networking failure or misconfiguration. Please try again later.

Troubleshooting

If you are receiving a status code 403: Unauthorized response then your account does not have sufficient privileges for the resource you are trying to access. Please contact Key Bridge 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.

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 keybridge:API services use 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

Specifications & Standards

keybridge systems and services are built using open standards and specifications. Read more about the open standards and use of today's most innovative technologies that make Key Bridge a de-facto standard for commercial White Space solutions.

Core Standards

  • AJAX
  • iCalendar & Microformat
  • JSR-168
  • JSR-127
  • JSR-170
  • JSR-314 (JSF 2.0)
  • OpenSearch
  • CMIS

Web Service Formats

  • REST
  • RMI
  • SOAP
  • WebDAV
  • XML
  • JSON
  • Hessian Binary

Identity Management

  • LDAP
  • Oracle Access Manager
  • Open SSO
  • OAuth 1.0 & 2.0
  • Basic Username + Password

Security

  • Pluggable Authentication
  • Email Verification
  • Granular Permissioning
  • Session Management
  • Code & System Profiling
  • OWASP Practices

Open Architecture

  • Java J2EE/JEE 6
  • Hierarchical and extensible
  • Segmented user communities
  • Message-oriented architecture
  • Pluggable & Modular

Performance & Scalability

  • 3-Tiered System
  • Clustered and load balanced
  • In-memory Caching
  • Static Content Export
  • Real-time Performance Monitoring

Data Import/Export

  • JSR-170 Repository
  • CMIS 1.0 Support
  • Import & export:
    Office, CSV, PDF, TXT, XML
  • WebDAV

Calculator Engines

  • Spectrum Situational Awareness
  • Signal Propagation & Path Loss
  • Geographic Analysis
  • GeoData Transformation
  • Digital Elevation

User Interface

  • Integrated Bug reporting
  • Robust calendaring
  • Rich text editor (WYSIWYG)
  • Email based subscriptions
  • RSS

Communication with external systems requires robust inter-operability and we build upon several key specifications and open standards. Key Bridge also actively supports and contributes to a number of emerging specifications and standards, open data models and information encoding strategies.

keybridge systems and services support a number of geographic data encoding strategies, including:

SFA

Simple Feature Access (SFA; also called ISO 19125), is both an OpenGIS and ISO Standard that specifies a common storage model of geographical data (point, line, polygon, multi-point, multi-line, etc.) using well-known text (or binary). See below for more.

GeoJSON

Geospatial JavaScript Object Notation (GeoJSON) is a geospatial data interchange format based on JavaScript Object Notation (JSON). A GeoJSON object may represent a geometry, a feature, or a collection of features, which themselves contain a geometry object and additional properties.

GML

Geography Markup Language (GML) is an XML grammar defined by the Open Geospatial Consortium (OGC) and also adopted as ISO 19136:2007 to express geographical features. GML is a modeling language for geographic systems and an open interchange format.

KML

Keyhole Markup Language (KML) is an XML notation for expressing geographic annotation and visualization within Internet-based, two-dimensional maps and three-dimensional Earth browsers. KML is most popularly used with the Google Earth software application.

Specifications Incorporated by Reference

SFA: Well Known Text

The default geometric coding employed by all keybridge:API services is defined in the White Space Information Format (WSIF) and relies upon a subset of classes defined in the Simple Feature Access (SFA) Geometry model. These are: Point, MultiPoint, Polygon, MultiPolygon, LineString and MultiLineString, which are themselves implementations of the SFA Geometry object interface and, by definition, may include a SFA SpatialReferenceSystem and a SFA MeasureReferenceSystem.

In the WSIF specification only a SpatialReferenceSystem is allowed, which is used to identify and persist the geodetic datum. Any MeasureReferenceSystem entry should be ignored if present.

The most commonly encountered geometry object a Point, with extended areas (e.g. buildings, facilities and contours) represented as Polygons and MultiPolygons.

The SFA Polygon

A Polygon is a planar Surface defined by one (1) exterior boundary (defined by a closed LinearRing) and zero (0) or more interior boundaries (also defined by one or more closed linear rings). Each interior boundary defines a hole in the Polygon. The exterior boundary linear ring defines the “top” of the surface as is the side of the surface from which the exterior boundary appears to traverse the boundary in a counter clockwise direction (e.g. following the right-hand-rule).

Interior LinearRings will have the opposite orientation, and appear as clockwise when viewed from the “top”. The rules that define valid polygons are as follows:

  1. Polygons are topologically closed (i.e. the exterior boundary is by a closed LinearRing);
  2. The boundary of a Polygon consists of a set of LinearRings that make up its exterior and interior boundaries;
  3. No two rings in the boundary cross; boundary rings may intersect at a Point but only as a tangent
  4. A Polygon may not have cut lines, spikes or punctures
  5. The interior of every Polygon is a connected point set;
  6. The exterior of a Polygon with 1 or more holes is not connected; that is, each hole defines a connected component of the exterior.

The combination of (a) and (c) makes a polygon a regular closed point set and a simple geometric objects.

The SFA MultiPolygon

A MultiPolygon is a MultiSurface whose elements are Polygons. The assertions for multi-polygons are:

  1. The interiors of 2 Polygons that are elements of a MultiPolygon may not intersect.
  2. The boundaries of any 2 Polygons that are elements of a MultiPolygon may not “cross” and may touch at only a finite number of Points.
  3. A MultiPolygon is defined as topologically closed.
  4. A MultiPolygon may not have cut lines, spikes or punctures; a MultiPolygon is a regular closed Point set:
  5. The interior of a MultiPolygon with more than 1 Polygon is not connected; the number of connected components of the interior of a MultiPolygon is equal to the number of Polygon in the MultiPolygon.
The boundary of a MultiPolygon is a set of closed curves (LineStrings) corresponding to the boundaries of its element Polygons. Each curve in the boundary of the MultiPolygon is in the boundary of exactly 1 element Polygon, and every curve in the boundary of an element Polygon is in the boundary of the MultiPolygon.


Back to top