This document presents the HTTP API for clients to read and update Sh data and that the microservice uses to notify clients.

Sections in this guide

Notices

Copyright © 2014-2019 Metaswitch Networks. All rights reserved

This manual is issued on a controlled basis to a specific person on the understanding that no part of the Metaswitch Networks product code or documentation (including this manual) will be copied or distributed without prior agreement in writing from Metaswitch Networks.

Metaswitch Networks reserves the right to, without notice, modify or revise all or part of this document and/or change product features or specifications and shall not be responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials.

Metaswitch and the Metaswitch logo are trademarks of Metaswitch Networks. Other brands and products referenced herein are the trademarks or registered trademarks of their respective holders.

Sh Cache Microservice API

Overview

This service provides an HTTP interface to the Sh protocol (3GPP TS 29.328 & 29.329) for accessing cached subscriber data from the HSS.

Clients may read all Sh data references that the HSS allows.

Updates may only be performed on Repository Data (data reference 0).

Clients may only subscribe to UE Reachability for IP (data reference 25).

In addition to error codes described here, as required by the HTTP RFCs the server may return 401 Unauthorized if the necessary security context not present, 403 Forbidden if the provided security context is insufficient for the requested operation, and appropriate 5xx status codes in the case of server errors. See RFC7231, RFC7235 and related RFCs for details.

Version information

Version : 1.0.0

Contact information

Contact Email : api-support@metaswitch.com

License information

License : Proprietary
License URL : https://www.metaswitch.com
Terms of service : null

URI scheme

BasePath : /shcache/v1

Tags

  • read : Operations for reading Sh user data. Cached data is used where available, otherwise the HSS will be contacted.

  • update : Operations for updating Sh user data. Updated values are propagated to the HSS and cached if successful.

  • subscribe : Operations that subscribe to changes in Sh user data.

  • management : Operations for managing the state of the Sh cache.

  • infrastructure : Infrastructure API for checking the health of the microservice.

Resources

Read

Operations for reading Sh user data. Cached data is used where available, otherwise the HSS will be contacted.

User Data Request
GET /{data_references}/{user_id}
Description

Retrieves one or more Sh data references for a single public identity.

The public identity, data references and other parameters are specified in the request URL.

The parameters required depend on the data references that are requested. See the parameter definitions for details, and also 3GPP TS 29.328 Table 7.6.1.

The server will retrieve the data reference values from its cache, querying the HSS if the data is not in the cache.

If successful, the response body will be an XML Sh-Data document using the schema ShDataType_Rel11.xsd specified in 3GPP TS 29.328.

Parameters
Type Name Description Schema

Path

data_references
required

Standard Sh data references available in the HSS for reads.

Excludes "UE Reachability for IP", this is handled separately by Subscribe to UE Reachability.

See 3GPP TS 29.328 Table 7.6.1.

< enum (repository_data, ims_public_identity, ims_user_state, scscf_name, initial_filter_criteria, location_information, user_state, charging_information, msisdn, psi_activation, dsai, service_level_trace_info, ip_address_secure_binding_info, service_priority_level, sms_registration_info, tads_information, stn_sr, ue_srvcc_capability, extended_priority, csrn, reference_location_information) > array

Path

user_id
required

IMS Public User Identity, Public Service Identity, or MSISDN of the user for whom the data is required.

string

Query

as_name
optional

Application server name, the SIP URI of the application server.

Required by data references:

  • initial_filter_criteria

  • dsai

See 29.329 §6.3.9.

string

Query

current_location
optional

Indicates whether an active location retrieval has to be initiated or not, when an AS requests location information.

  • 0: active location retrieval is not required

  • 1: requests that active location retrieval is initiated

Required by data references:

  • 'location_information'

See 29.329 §6.3.8.

integer

Query

dsai_tags
optional

The DSAI-Tags identifying the instance of the Dynamic Service Activation Information being accessed for the Public Identity.

Required by data references:

  • dsai

See 29.329 §6.3.18.

< string > array

Query

local_tz_indication
optional

Optional. Indicates that the Local Time Zone information (time zone and daylight saving time) of the visited network where the UE is attached is requested with or without other location information.

Used by data references:

  • location_information

See 29.329 §6.3.27.

enum (only_local_tz, local_tz_with_location_info)

Query

private_id
optional

The IMS Private User Identity (IMPI) of the user for whom the data is requested.

See 23.003 §13.3.

string

Query

requested_domain
optional

The access domain for which the data is requested.

Required by data references:

  • 'location_information'

  • 'user_state'

See 29.329 §6.3.7.

enum (cs, ps)

Query

requested_identity_set
optional

The requested set of IMS Public Identities.

Used by data references:

  • ims_public_identity

See 29.329 §6.3.10.

< enum (all, registered, implicit, alias) > array

Query

requested_nodes
optional

Optional. A bitmask specifying for which access node types the data is requested.

Only applies when 'requested_domain' is 'ps'.

  • Bit 0: MME

  • Bit 1: SGSN

Used by data references:

  • location_information

  • user_state

See 29.329 §6.3.7A.

integer

Query

service_ind
optional

Service indication(s) to retrieve.

Identifies the sets of service-specific transparent data that is being requested.

Required by data references:

  • repository_data

See 29.329 §6.3.5.

< string > array(csv)

Query

serving_node_indication
optional

If present it indicates that the sender does not require any location information other than the Serving Node Addresses/Identities requested (e.g. MME name, VLR number).

Other location information (e.g. Global Cell ID, Tracking Area ID) may be absent.

Used by data references:

  • location_information

See 29.329 §6.3.23.

enum (only_serving_nodes_required)

Query

udr_flags
optional

Optional. A bitmask requesting additional information as part of a location information request.

  • Bit 0: Location-Information-EPS-Supported

  • Bit 1: RAT-Type-Requested

Used by data references:

  • location_information

See 29.329 §6.3.28.

integer
Responses
HTTP Code Description Schema

200

Data was retrieved successfully. Message body is Sh-Data XML using schema ShDataType_Rel11.xsd.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

string (byte)

400

Bad request.

The information provided was invalid or not sufficient to complete the request.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

403

Forbidden.

The operation is not allowed to proceed with the parameters given.

error

404

Not found.

The data for the given public identity was not found. Service received a 5001 or 5030 response from the HSS.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

424

Failed Dependency.

An unrecoverable error was received from a dependent service, such as the HSS. Technically a 5xx-class error, but we don’t want to trigger unwanted retries or blacklisting from linkerd or other service meshes.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

default

unexpected error

error
Produces

  • application/xml

Example HTTP request
Request path 
/string/string
Example HTTP response
Response 200 
"string"
Response 400 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 403 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 404 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 424 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response default 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}

Update

Operations for updating Sh user data. Updated values are propagated to the HSS and cached if successful.

Profile Update Request
PUT /{data_reference}/{user_id}
Description

Creates or updates a single data reference or service indication.

The request body is an XML Sh-Data document using the schema ShDataType_Rel11.xsd specified in 3GPP TS 29.328.

The document must contain the correct Sh-Data XML for the data reference. In case the data reference is RepositoryData, the Sh-Data/RepositoryData`element has to contain the same`ServiceIndication`as specified as a parameter, and the correct`SequenceNumber`

The server will perform a Profile-Update-Request operation with the HSS, and, if successful, update the value stored in its cache.

Parameters
Type Name Description Schema

Path

data_reference
required

Standard Sh data references available in the HSS for updates.

See 3GPP TS 29.328 Table 7.6.1.

enum (repository_data, psi_activation, dsai, sms_registration_info, stn_sr)

Path

user_id
required

IMS Public User Identity, Public Service Identity, or MSISDN of the user for whom the data is required.

string

Query

service_ind
optional

Service indication to update.

Identifies the service-specific transparent data that is being updated.

Required by data references:

  • repository_data

See 29.329 §6.3.5.

string

Body

data
optional

string (byte)
Responses
HTTP Code Description Schema

200

Updated
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

No Content

201

Created
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

No Content

400

Bad Request
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

403

Forbidden.

The operation is not allowed to proceed with the parameters given.

error

404

Not found.

The user or service indication was not found. Service received a 5001 or 5030 response from the HSS.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

409

Conflict.

Transparent data out of sync. Service received a 5105 experimental response from the HSS.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

424

Failed Dependency.

An unrecoverable error was received from a dependent service, such as the HSS. Technically a 5xx-class error, but we don’t want to trigger unwanted retries or blacklisting from linkerd or other service meshes.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

default

unexpected error

error
Consumes

  • application/xml

Example HTTP request
Request path 
/string/string
Request body 
{ }
Example HTTP response
Response 400 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 403 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 404 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 409 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 424 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response default 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}

Subscribe

Operations that subscribe to changes in Sh user data.

Subscribe to UE Reachability
POST /ue_reachability_for_ip/{user_id}
Description

Subscribe to be notified when the UE is reachable over IP. The client must provide a callback URL at which it will receive the notification.

The server will send a Subscribe-Notification-Request to the HSS, requesting to be notified when the UE becomes reachable over IP.

When the HSS notifies the Sh Cache server, the client will be notified at the callback URL it provided.

Parameters
Type Name Description Schema

Path

user_id
required

IMS Public User Identity, Public Service Identity, or MSISDN of the user for whom the data is required.

string

Query

private_id
optional

The IMS Private User Identity (IMPI) of the user for whom the data is requested.

See 23.003 §13.3.

string

Body

body
required

Specifies the subscription expiry and notification information.

UEReachabilityRequest
Responses
HTTP Code Description Schema

200

OK
Headers :
X-Sh-Subscription-Expiry (string (date-time)) : The UTC expiry time granted by the HSS.
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

No Content

400

Bad request
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error

403

Forbidden.

The operation is not allowed to proceed with the parameters given.

error

404

Not found.

The user was not found. Service received a 5001 or 5030 response from the HSS.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

No Content

424

Failed Dependency.

An unrecoverable error was received from a dependent service, such as the HSS. Technically a 5xx-class error, but we don’t want to trigger unwanted retries or blacklisting from linkerd or other service meshes.
Headers :
X-Diameter-Result-Codes (< string > array) : Comma-separated list of data references or service indications and the diameter result codes for each query. Service indications will be prefixed by the repository_data data reference. We assume that the service indication does not include the = character. Experimental diameter result code will be prefixed with a vendor ID. eg. data_ref1=xxxx,repository_data:service_indication=xxxx,data_ref2=vendorId:xxxx.

error
Consumes

  • application/json

Example HTTP request
Request path 
/ue_reachability_for_ip/string
Request body 
{
  "expires" : 10,
  "notification_url" : "http://myservice.example.com:8000/",
  "notification_data" : "my-request-id"
}
Example HTTP response
Response 400 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 403 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Response 424 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}

Management

Operations for managing the state of the Sh cache.

Invalidate cached data for all data references
DELETE /management/cache
Description

Invalidates all cache entries for all data references, or all cache entries for a particular user if user_id is supplied.

Subsequent cache operations will repopulate the cache from the HSS.

Parameters
Type Name Description Schema

Query

invalidate_subscriptions
optional

Specifies whether subscription data will be invalidated as well as the cached data.

boolean

Query

user_id
optional

IMS Public User Identity, Public Service Identity, or MSISDN of the user for whom the data is required.

string
Responses
HTTP Code Description Schema

200

OK

No Content

400

Bad Request

error
Example HTTP request
Request path 
/management/cache
Example HTTP response
Response 400 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Invalidate all cached data for the data reference
DELETE /management/cache/{data_reference}
Description

Invalidates all cache entries for the given data reference. Subsequent cache operations will repopulate the cache from the HSS.

If data_reference is repository_data and service_ind is specified, just the repository data for that service indication is invalidated. Otherwise, all repository data is invalidated.

Parameters
Type Name Description Schema

Path

data_reference
required

Standard Sh data references available in the HSS for updates.

See 3GPP TS 29.328 Table 7.6.1.

enum (repository_data, psi_activation, dsai, sms_registration_info, stn_sr)

Query

invalidate_subscriptions
optional

Specifies whether subscription data will be invalidated as well as the cached data.

boolean

Query

service_ind
optional

Service indication to update.

Identifies the service-specific transparent data that is being updated.

Required by data references:

  • repository_data

See 29.329 §6.3.5.

string
Responses
HTTP Code Description Schema

200

OK

No Content

400

Bad Request

error
Example HTTP request
Request path 
/management/cache/string
Example HTTP response
Response 400 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}
Invalidate all cached data for the data reference and user
DELETE /management/cache/{data_reference}/{user_id}
Description

Invalidates all cache entries for the given data reference and user. Subsequent cache operations will repopulate the cache from the HSS.

If data_reference is repository_data and service_ind is specified, just the user’s repository data for that service indication is invalidated. Otherwise, all repository data for the user is invalidated.

Parameters
Type Name Description Schema

Path

data_reference
required

Standard Sh data references available in the HSS for updates.

See 3GPP TS 29.328 Table 7.6.1.

enum (repository_data, psi_activation, dsai, sms_registration_info, stn_sr)

Path

user_id
required

IMS Public User Identity, Public Service Identity, or MSISDN of the user for whom the data is required.

string

Query

invalidate_subscriptions
optional

Specifies whether subscription data will be invalidated as well as the cached data.

boolean

Query

service_ind
optional

Service indication to update.

Identifies the service-specific transparent data that is being updated.

Required by data references:

  • repository_data

See 29.329 §6.3.5.

string
Responses
HTTP Code Description Schema

200

OK

No Content

400

Bad Request

error
Example HTTP request
Request path 
/management/cache/string/string
Example HTTP response
Response 400 
{
  "origin" : "credentials",
  "errorID" : "identityNotUnique",
  "message" : "A credentials record with the specified identity (%1) already exists. The record with internal ID %2 has that identity.",
  "variables" : [ "tel:+12025550171", "ca8a8a04-9257-4093-97f7-ff27b8503e4c" ],
  "requestID" : "a9d432e4-42c4-43b8-8492-4be76840546b"
}

Infrastructure

Infrastructure API for checking the health of the microservice.

Check the microservice is working correctly.
GET /infra/up
Description

Check that the microservice is working correctly. Dependencies (e.g. other microservices and underlying datastores) are not checked, so a successful response from this API does not guarantee that the full stack is working.

This endpoint may be suitable for health-checking a microservice instance.

A 204 response indicates that the microservice is working correctly. Any 5xx response or no response at all indicates a problem.

Responses
HTTP Code Description Schema

204

Success. The microservice is up.

No Content
Example HTTP request
Request path 
/infra/up
Check that the microservice is in service and ready to receive requests on this API.
GET /infra/ready
Description

Check that the microservice is in service and ready to receive requests on this API. The microservice performs end-to-end checking of its function (typically by generating some synthetic transactions).

This check should fail if there is no possibility of a typical request succeeding - perhaps because the microservice has not yet received initial configuration, or because it is not currently connected to one or more dependencies.

This endpoint may be suitable for use by a load-balancer when determining whether to pass service requests to this instance.

A 204 response indicates that the microservice is working correctly and ready to provide service. Any 5xx response or no response at all indicates a problem.

Responses
HTTP Code Description Schema

204

Success. The microservice is ready to provide service.

No Content
Example HTTP request
Request path 
/infra/ready

Definitions

UEReachabilityRequest

Name Description Schema

expires
optional

Expiry time in seconds
Example : 10

integer

notification_data
optional

Opaque data that will be sent in the notification request.
Example : "my-request-id"

string

notification_url
required

URL no notify when UE becomes reachable.
Example : "http://myservice.example.com:8000/"

string

error

Details of an error.

Name Description Schema

errorID
required

A short ID which, when combined with origin, uniquely identifies the error.
Example : "string"

string

message
required

A human readable explanation of the error - intended for API client writers. This can optionally contain %number text to refer to variables. There must be at least that many variables in the variables array.
Example : "string"

string

origin
required

The microservice from which the error originated. The combination of origin and errorID uniquely identify the error.
Example : "string"

string

requestID
optional

The internal ID of the request which caused the error.
Example : "string"

string

variables
optional

The items inserted into %number placeholders in the message.
Example : [ "string" ]

< string > array

Sh Cache Notification API

Overview

This is a callback API that Sh Cache Microservice API clients use to receive notifications from the server. At this time notifications are only supported for the "UE Reachability for IP" Sh data reference.

The basePath "/" is used because the API operations will be performed using whatever notification URL was passed to the Sh Cache microservice’s subscribe_ue_reachability operation.

In addition to error codes described here, as required by the HTTP RFCs the server may return 401 Unauthorized if the necessary security context not present, 403 Forbidden if the provided security context is insufficient for the requested operation, and appropriate 5xx status codes in the case of server errors. See RFC7231, RFC7235 and related RFCs for details.

Version information

Version : 1.0.0

Contact information

Contact Email : api-support@metaswitch.com

License information

License : Proprietary
License URL : https://www.metaswitch.com
Terms of service : null

URI scheme

BasePath : /

Tags

  • notify : Operations for notifying the client.

Resources

Notify

Operations for notifying the client.

POST /
Description

Notifies the Sh Cache Microservice client that the "UE Reachability for IP" data reference it previously subscribed to has been updated.

The request body is an XML Sh-Data document using the schema ShDataType_Rel11.xsd specified in 3GPP TS 29.328.

This contains the Sh-Data/Sh-IMS-Data/Extension/Extension/Extension/UEReachabilityForIP element that the microservice received from the HSS in the Push-Notification-Request.

Parameters
Type Name Description Schema

Query

data
required

Opaque data sent in the corresponding request from the client.

string
Responses
HTTP Code Description Schema

200

OK

No Content

400

Bad Request

No Content
Consumes

  • application/xml

Example HTTP request
Request path 
/?data=string