Web Service Calls - larz7/larzworksamples GitHub Wiki

Overview

This document describes data types used to make web service calls.

Authentication

Communication with the web service is encrypted using server SSL. Requests are authenticated via the web service. You will need distinct service credentials for each supported environment.

Be sure to specify the following.

  • Client service
  • Client business
  • Target environment

Once your application has been registered you will get a 2-legged client access token that can be used for subsequent requests. This token must be refreshed before its expiry or after it is invalidated. The token is base-64 encoded and may be decoded to view additional context about your client (e.g. business ID). Tampering with the token will result in a 401 UNAUTHORIZED error.

Note: For other APIs, a 3-legged user access token required.

Example headers:

Content-Type: application/json
Authorization: Bearer 9FDF4NG5ZQB0I0U00S4EM2Y4PPCE4WLHV3LBLMMU:+RtakbK0d5g7OcGRIbThlwk2fUM=

Multi-tenancy support

To support multiple tenants of the system via a single API, a concept of business IDs is introduced in int-service version 7. Most system entities now have one or more business IDs assigned to them. If the caller is associated with a non-host business, this will automatically be set on creation to the caller's business ID. The business ID set by host callers will be respected upon creation. All subsequent reads and updates will validate the caller's business ID against the entity's.

Example 1:

  • Register IPTV (business ID = 2) client.
  • Call create package with IPTV client token.
  • Business ID is ignored on the request set to IPTV (2).
  • IPTV and host clients may read and update the package, go90 clients will get a 403 FORBIDDEN response if they attempt access.

Example 2:

  • Register host (business ID = 0) client.
  • Call create channel API with host client token and business IDs set to go90 (1) and IPTV (2).
  • Request business IDs will be respected and set on the channel.
  • Host clients may read and update the channel. Attempts by non-host clients to update the channel will result in a 403 FORBIDDEN response.

Date and time-related data

All dates, times, and duration must be expressed using ISO 8601 formatting. Specifically:

  • Durations/periods - PnYnMnDTnHnMnS
  • Dates - YYYY-MM-DD
  • Date/times - YYYY-MM-DDThh:mm:ss.SSSZ

In the service, periods are distinct from duration (following the Joda-Time convention). A duration is an exact measurement of an interval that is not dependent upon a specific chronology. A period is exact only within the context of a specific chronology, such as the Gregorian calendar or ISO 8601. Periods can be used to express inexact intervals such as P1M (1 month); attempting to represent P1M as a duration will cause an error.

Data Types

Market

Market is identified by a unique MarketId and has the following properties :

Property Required Type Description
id Y Long An internal unique Market identifier for Koseki
externalId Y Long An external Market identifier which will be provided by Verizon
type Y MarketType Type of the Market used whether it is postal code, region or cilli code
businessId Y Long One business owner for the Market. Multiple markets can have the same business owner
status Y MarketStatus Status of the Market whether it is disabled, enabled or active
name Y String Market name
startDate Y DateTime Start date
endDate N DateTime End date

The following sections describe enumerations used when constructing Market metadata.

MarketType

  • Region - Region
  • PostalCode - Postal code for the market area
  • Cilli - Cilli code for the market area

MarketStatus

  • Disabled - Market is disabled.
  • Active - Market is active.
  • Enabled - Market is enabled.

Methods

Create Market

Creates a new market

HTTP Method: POST

Path: /v1/market

URL Parameters: None

Query String: None

Required HTTP Headers:

Content-Type - application/json

Request Body:

{
	"id": 10,
	"externalId":92255,
	"type": "Region",
	"businessId": 1,
	"status": "Disabled",
	"name": "Albany",
	"startDate": "2016-02-05T08:00:00.000Z",
	"endDate": null
}

Success Response:

200 OK
<true|false>

Failure Responses:

400 BAD_REQUEST - JSON is malformed or failed validation.

401 UNAUTHORIZED - Missing or invalid HMAC headers.

403 FORBIDDEN - Client business may not access one or more request entities.

500 INTERNAL_SERVER_ERROR - Unexpected error on server.

Additional error details are present in the response body.

Get Market by Id

Retrieves market by market identifier

HTTP Method: GET

Path: /v1/market/<MarketId>

Required HTTP Headers: Content-Type - application/json; charset=utf-8

Sample Request:

GET /v1/market/92255

Sample Response:

{
	"id": 10,
	"externalId":92255,
	"type": "Region",
	"businessId": 1,
	"status": "Disabled",
	"name": "Albany",
	"startDate": "2013-01-01T08:00:00.000Z",
	"endDate": null
}

Failure Responses:

400 BAD_REQUEST - JSON is malformed or failed validation.

401 UNAUTHORIZED - Missing or invalid HMAC headers.

403 FORBIDDEN - Client business may not access one or more request entities.

500 INTERNAL_SERVER_ERROR - Unexpected error on server.

Additional error details are present in the response body.

Get Market by Name

Retrieves market by market name

HTTP Method: GET

Path: /v1/market/<MarketName>

Required HTTP Headers:

Content-Type - application/json; charset=utf-8

Sample Request:

GET /v1/market/Albany

Success Response:

{
	"id": 10,
	"externalId":92255,
	"type": "Region",
	"businessId": 1,
	"status": "Disabled",
	"name": "Albany",
	"startDate": "2013-01-01T08:00:00.000Z",
	"endDate": null
}

Failure Responses:

400 BAD_REQUEST - JSON is malformed or failed validation.

401 UNAUTHORIZED - Missing or invalid HMAC headers.

403 FORBIDDEN - Client business may not access one or more request entities.

500 INTERNAL_SERVER_ERROR - Unexpected error on server.

Additional error details are present in the response body.

Retrieve Markets

Retrieves markets

HTTP Method: GET

Path: /v1/markets

Required HTTP Headers:

Content-Type - application/json; charset=utf-8

Sample Request:

GET /v1/markets

Success Response:

{
  "total": 8,
  "remaining": 0,
  "nextOffset": null,
  "results": [
    {
      "id": 1,
      "externalId":92254,
      "type": "Region",
      "businessId":1,
      "status": "Disabled",
      "name": "New York",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    },
    {
          "id": 2,
          "externalId":92562,
          "type": "Region",
          "businessId":1,
          "status": "Disabled",
          "name": "New York",
          "startDate": "2013-01-01T08:00:00.000Z",
          "endDate": null
    },
    {
      "id": 3,
      "externalId":91918,
      "type": "Region",
      "businessId":1,
      "status": "Disabled",
      "name": "Philadelphia",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    },
    {
      "id": 4,
      "externalId":602,
      "type": "Region",
      "businessId":2,
      "status": "Disabled",
      "name": "Chicago",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    },
    {
      "id": 5,
      "externalId":753,
      "type": "Region",
      "businessId":2,
      "status": "Disabled",
      "name": "Phoenix",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    },
    {
      "id": 6,
      "externalId":803,
      "type": "Region",
      "businessId":1,
      "status": "Disabled",
      "name": "Los Angeles",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    },
    {
      "id": 7,
      "externalId":807,
      "type": "Region",
      "businessId":2,
      "status": "Active",
      "name": "San Francisco - Oakland - San Jose",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    },
    {
      "id": 8,
      "externalId":820,
      "type": "Region",
      "businessId":1,
      "status": "Disabled",
      "name": "Portland, OR",
      "startDate": "2013-01-01T08:00:00.000Z",
      "endDate": null
    }
  ]
}

Failure Responses:

400 BAD_REQUEST - JSON is malformed or failed validation.

401 UNAUTHORIZED - Missing or invalid HMAC headers.

403 FORBIDDEN - Client business may not access one or more request entities.

500 INTERNAL_SERVER_ERROR - Unexpected error on server.

Additional error details are present in the response body.

Set status of a Market

Update the status of a market identified by the unique identifier

HTTP Method: PUT

Path: /v1/market/<MarketId>/<MarketStatus>

Required HTTP Headers:

Content-Type - application/json; charset=utf-8

Sample Request:

PUT /v1/market/504/Active

Success Response:

200 OK
<true|false>

Failure Responses:

400 BAD_REQUEST - JSON is malformed or failed validation.

401 UNAUTHORIZED - Missing or invalid HMAC headers.

403 FORBIDDEN - Client business may not access one or more request entities.

500 INTERNAL_SERVER_ERROR - Unexpected error on server.

Additional error details are present in the response body.

Update Market

HTTP Method: PUT

Path: /v1/market

URL Parameters:

Query String:

Required HTTP Headers:

Content-Type - application/json

Sample Request:

PUT /v1/market/

Success Response:

200 OK
<true|false>

Failure Responses:

400 BAD_REQUEST - JSON is malformed or failed validation.

401 UNAUTHORIZED - Missing or invalid HMAC headers.

403 FORBIDDEN - Client business may not access one or more request entities.

500 INTERNAL_SERVER_ERROR - Unexpected error on server.

Additional error details are present in the response body.

⚠️ **GitHub.com Fallback** ⚠️