Overview

BEAP and HAPI are the Web interfaces for the Bloomberg Data License Platform. The Data License Platform Guide provides a general overview of the platform and its capabilities. HAPI is the REST API for the Bloomberg Data License Platform, which powers BEAP.

You can use HAPI to access any capability or data that is accessible through BEAP: for example to automate the retrieval of bulk datasets and Bloomberg metadata; or to request, schedule and retrieve custom datasets using reusable resources.

Getting Started

To get started with HAPI you need to :

• Register your application at https://console.bloomberg.com/
• Obtain a set of credentials for your application at https://console.bloomberg.com/
• Add your IP address to the allowlist for your application at https://console.bloomberg.com/
• Download sample code at https://service.bloomberg.com/
• Use the sample code to connect to the entryPoint at https://api.bloomberg.com/eap/
• Explore BEAP, a WEB UI that is powered by HAPI, to get familiar with HAPI concepts. Login at https://eap.bloomberg.com/
• Register for AWS Cloudfront Signed URL delivery at https://service.bloomberg.com/portal/tickets/new

Interacting with HAPI

HAPI is a JSON API. All HAPI JSON responses are also valid JSON-LD, expressed using the BEAP Ontology, which is based on the LDP and Hydra vocabularies.

Authentication and Authorization

Each request to HAPI must include a JSON Web Token (JWT) header, unique to and matching the request. The token must be signed with a valid Data License credential (see sample code). The Data License Platform verifies that the token corresponds to the endpoint being requested and is unique. The Platform also checks the credential used to sign the token, to verify access rights to the resource being requested.

Credentials and permitted IP address allowlists are managed through https://console.bloomberg.com/.

The credentials must be

1. Issued by a Data License account with active Bloomberg Data License agreements.
2. Unexpired
3. Configured with a permitted IP allowlist entry for the address issuing the request.

HAPI supports server mode OAuth Authentication Flow. Hybrid and device modes are not supported.

Navigate to Enterprise Console > Develop > Developer Documentation > API References > Authentication & Authorization to learn more about HAPI authentication.

Search

• Many collection endpoints provide search templates that can be used to query them, including full text search. These are provided using the Hydra search property.
• Ordering of the returned results is controlled by the sort query parameter.
• Other sort fields such as title can be used

• The default sort order is ascending. If the sort field is prefixed with - it will return results in descending order, e.g. https://api.bloomberg.com/eap/catalogs/bbg/datasets/?sort=-titlePagination

• Paging sequence bounds for paged collections will always be indicated with first and last links (either in the LDP-Paging headers or in the Hydra PartialCollectionView).

• Within a paging sequence, a next link will be present on all pages except the last and a prev link will be present on all pages except the first, to aid sequential traversal.
• Pages beyond the paging sequence bounds will return a response with an empty collection.
• Pages beyond the paging sequence bounds will not have next or prev links.

• Pages that support the pageSize query parameter permit a user defined pageSize.Redirects

• latest represents the most recently created resource in a particular collection. It is currently applicable for the snapshots endpoints. Since "latest" changes meaning over time, this a convenience shortcut rather than a canonical resource.

• Request a historic time series over a specified date range and period through HAPI by POSTing a resource of type HistoryRequest to /catalogs/{catalog}/requests/.While Bloomberg Data License makes every effort to maintain stable URLs, API users should receive and process HTTP redirect codes, and must specify a header to determine the version of the API to which they are coding (this document describes version 2) .Rate LimitingThe number of requests is currently limited to 1000 requests per second per IP address, and 1200 requests per minute per application. An application in this context is defined as a Bloomberg Enterprise Console Application. Any request rate greater than this number will be rejected with an HTTP error code of 429.CompressionBy default all datasets are returned uncompressed. You can negotiate gzip compression by setting the "Accept-Encoding" request header to "gzip" as per rfc2612.New FeaturesPush NotificationsTo avoid polling the REST APIs for new distributions, HAPI provides an API for receiving push notifications when distributions become available. We provide a W3C Server Sent Event Stream to push notifications to connected clients over HTTP. Subscribe to the event stream at the /notifications/sse endpoint to receive push notifications of DistributionPublishedActivity events for Bulk and Custom dataset publications immediately when they are available.History Requests

• In HAPI V2, fieldLists are strongly typed to match the request type. HAPI V1 fieldLists are only supportd for requests of type DataRequest

• Security level overrides are ignored by history requests.

AWS CloudFront Signed URLs

To meet the increasing demand to access Bloomberg Data License data in the public cloud, HAPI users who register for cloud-enabled delivery can download bulk datasets directly from AWS S3 via a CloudFront signed URL, providing temporary access to the bulk dataset as an S3 object in a Bloomberg managed virtual private cloud. Once a client is cloud-enabled, HAPI responds to requests to download bulk (Bloomberg Catalog) distribution resources with a 303 status code. The location header provides a signed URL for an AWS S3 resource that can be accessed directly from AWS through CloudFront's content delivery network. The signed URL expiration time is 5 minutes.

Show Subscribed Datasets

Filter by datasets to which you have subscribed with query parameter subscribed=true when getting /catalogs/bbg/datasets/.

Extended Pagination

Specify page size against supported endpoints with query parameter pageSize.

Request References

Where a resource is referenced by an active (scheduled) request, and updates to that resource are restricted, the boolean property referencedByActiveRequests will be set to true.

Release Notes - All Users

This specification introduces HAPI Version 2. Code written using HAPI Version 1 must be modified to accomodate these changes.

Upgrading to HAPI V2

You can enable access to HAPI V2 using the apiVersion header (see Version Headers for more details).

Clients requesting bulk datasets should review their V1 API code against the following release notes:

• Version Headers
• Consolidation of Members and Contains
• Context and BEAP Ontology
• Dataset Type Simplification

Clients requesting custom datasets should refer to the simplified model for custom dataset request submission and management.

Version Headers

Every request to HAPI must include an apiVersion header (set to apiVersion to 2 for the version described by this specification. Existing clients already using the HAPI Version 1 may set apiVersion to 1 to access the previous version during a transition period. These are the only supported values for apiVersion. Requests that do not set the apiVersion header, and requests that provide an unsupported apiVersion header value will be rejected with a 400 response code.

Response headers include a latest-apiVersion which returns the latest available version of the api.

All HAPI resources, including the ones you have creates, are maintained across version 2 and version 1. This means:

• You can GET the resources you created in version 1 to see how to create them in version 2 by changing the apiVersion header.
• Resources created by version 2 are also accesible to version 1, excluding historyRequests which are not supported in version 1.
• You can parallel run a version 2 application alongside your existing version 1 application while you are preparing to migrate.

The previous API specification is available at: https://eap.bloomberg.com/docs/HAPI/v1/. Access to this previous version requires access to BEAP (https://eap.bloomberg.com).

Consolidation of Members and Contains

members is now replaced by contains

HAPI responses have been rationalised, to eliminate duplicate information in responses. The members (hydra:members) property has been retired from all responses. In HAPI version 1 the contains (ldp:contains) property provided a list of resource locations relative to the parent resource. In HAPI version 2 contains now provides all the properties which used to be provided by members; the relative resource location provided in V1 is now provided by the @id property in V2.

You can compare V1 and V2 responses for yourself by setting the apiVersion header to 1 or 2 in your test HAPI requests (see Version Headers).

Context and BEAP Ontology

The BEAP Ontology is a newly introduced RDF vocabulary designed to facilitate understanding of and interoperability with HAPI.

HAPI JSON-LD responses now refer to the BEAP Ontology as the default vocabulary (@vocab).

Dataset Type Simplification

The dataset response now returns a scalar value of Dataset for @type to simplify response processing.

Improved Error messages

Responses are now provided in JSON-API response format, including an RFC6901 pointer to each section of the submitted document that could not be processed.

Release Notes - Custom Datasets

This specification introduces HAPI Version 2. Code written using HAPI Version 1 that references then endpoints below must be modified to accomodate these changes:

/catalogs/{catalog}/requests/

/catalogs/{catalog}/universes/

/catalogs/{catalog}/fieldLists/

/catalogs/{catalog}/triggers/

Simplified Request Workflow

HAPI API version 2 introduces a simplified model for request submission and management.

API V1 WorkflowAPI V2 WorkflowNotesPOST/universes/{u}POST/universes/{u}V2 universe includes definition.POST/universes/{u}/definitionsV2 universe includes definition so not required.POST/triggers/{t}POST/triggers/{t}V2 trigger includes definition.POST/trigger/{t}/definititionsV2 trigger includes definition so not required.POST/fieldLists/{f}POST/fieldLists/{f}V2 fieldList includes definition.
V2 fieldList is strongly typed and must match the request type that references it (see strongly typed resources).POST/fieldLists/{f}/definititionsV2 fieldList includes definition so not required.POST/requests/{r}POST/requests/{r}V2 request includes definition.
V2 references universe, fieldList and trigger directly.
All requests reference the current version of these resources at the time of request submission.
V2 request type must match fieldList type (see strongly typed resources)POST/requests/{r}/definititionsV2 request includes definition so not required to submit the request.
V1 no longer permits submission of a request definition that references a "stale" (old) definition of a universe, fieldList or trigger.POST/requests/{r}/definitionsPATCH/requests/{u}Scheduled V2 requests may be cancelled if enabled is set to true by PATCHing enabled to false.POST/universes/{u}/definitionsPATCH/universes/{u}The content (i.e. the list of securities) of a V2 universe is modified by PATCH.
Scheduled requests apply the current universe definition at execution time for V1 and V2.POST/fieldLists/{f}/definitionsPATCH/fieldLists/{f}A fieldList may be PATCHed if the referencedByActiveRequests property is false.POST/triggers/{t}/definitionsPATCH/triggers/{t}A trigger may be PATCHed if the referencedByActiveRequests property is false.

Strongly Typed Resources and Structures

All resources and all structures within these resources are strongly typed using @type. All Types are validated on POST.

To simplify response processing, dataset responses now provide a scalar value for @type. This value allows a user to determine the nature of the content of the Dataset. A DataRequest will produce a Dataset; A HistoryRequest will produce a HistoryDataset.

Strongly Typed Dates DateTimes

issued and modified are now returned as UTC xsd:datetTime values, of the form "YYYY-MM-DDThh:mm:ss.ffffffZ".

scheduledTrigger properties are now strongly typed. startDate is an xsd:date. startTime is an xsd:time.

Standardized Security Identifiers

The valid set of security identifiers (such as "BB_GLOBAL", "BB_UNIQUE", "TICKER", "ISIN", "CUSIP", "SEDOL") are defined by the SecID enumeration of an identifierType.

See the contains property of a universe resource for details of this enumeration.

Security Level Overrides

The option fieldOverrides property of a universe have been simplifed into a flat structure that accepts either a cleanName or mnemmonic. HAPI now supports up to 19 security level overrides per requested security.

Pricing Source Options

The DataRequest pricingSourceOptions property replaces the V1 property pricingSource, to avoid confusion with the Data License field pricingSource.

Associated Request

The dataset property request replaces the property associatedRequest.

API Specification

This is the specification for the Bloomberg Data License Hypermedia API (HAPI).

https://anypoint.mulesoft.com/mocking/api/v1/sources/exchange/assets/e7d54e45-d3dc-4399-bdcd-16cbc65426a4/e-lab-gops-bloomberg-hapi-pp/1.0.0/m