Page tree

 

 

 

 

 

 

 

Geographic Site Management
API REST Specification

 

Document Number TMF674

October 2017

 

 

 

 

 

 

 

Release: Frameworx Release 17.5

Status: Member Evaluation

Version: 1.0.0

IPR Mode: RAND

NOTICE

Copyright © TM Forum 2017. All Rights Reserved.

 

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

Direct inquiries to the TM Forum office:

4 Century Drive
Suite 100
Parsippany, NJ 07054, USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

SAMPLE USE CASES

RESOURCE MODEL

GEOGRAPHIC SITE RESOURCE

Notification Resource Models

GeographicSite Creation Notification

GeographicSite Change Notification

API OPERATION TEMPLATES

Operations on Geographicsite

List sites

Register new site

Retrieve individual site

Complete update of an individual site

Partial update of an individual site

Delete an individual site

API NOTIFICATIONS

Register listener

Unregister listener

Publish Event to listener

Acknowledgements

Release History

Contributors to Document

List of Tables

 

N/A

 

Introduction

The following document is the specification of the REST API for Site Management. It includes the model definition as well as all available operations for SID GeographicSite entity.

 

This API covers the operations to manage (create, read, delete) sites that can be associated to a customer, an account, a service delivery or other entities.

This API defines a Site as a convenience class that allows to easily refer to places important to other entities, where a geographic place is the entity that can answer the question “where?”, allowing to determine where things are in relation to the earth's surface,  and can be represented either in a textual structured way (geographic address) or as a geometry referred to a  spatial reference system (geograpich location)

 

This API relates with the following two APIs also covering SID GeographicPlace entity

  • Address Management API, specific to manage places defined in a structured textual way (street name, street number, …)  and validate existence of given address definition.
  • GeoLocation API specific for management of places defined as a geometry in the spatial reference regarding the surface of the Earth (coordinates, …)  and the relationship between different geolocations (distance, proximity, …)

 

This API allows the following operations

  • Create a new site

 

  • Retrieve a list of sites stored in a server filtered by a given criteria

 

  • Retrieve a specific site

SAMPLE USE CASES

This section includes a set of main use cases that can be performed with this API. Additional use cases can be generated using the operations and resources defined in this specification.

  • Create a site in the server and associate a given customer/account to that site. The site definition includes all the address definition (street name, street number, ….) as well as the type of site it is in the relationship with the customer and the validity period for the relationship

 

  • Request a new product order and associate the delivery of any of the products/services in the order to one of the sites that have been associated to a customer/account

 

  • A customer creates a new trouble ticket for technical assistamce requiring an agent to provide assistance in an specific geographic address, identified as one of the sites allocated to the customer

 

 

RESOURCE MODEL

GEOGRAPHIC SITE RESOURCE

The GeographicSite resource represents an class that allows to easily refer to Places important to other entities (such as a customer, an account, a product, ….) .

Resource model

 

Lifecycle

No state machine for the resources detailed in this API

Field descriptions

GeographicSite fields

Field

Mandatory in API messages

Description

id

Yes in response

A string. Unique identifier of the site within the server

href

Yes in response

A string. An URI used to access to the site resource

name

Yes

A string. The name that the site is known by

description

No

A string. Text describing additional information  regarding the site

code

No

A string. A code that may be used for some addressing schemes e.g. [ANSI T1.253-1999]

status

Yes in response

A string. The condition of the GeographicSite, such as active, inactive, planned

address

Yes if geographicLocation not included

An address (GeographicAddress) passed by reference or by value. Used to identify the physical place over the surface of the Earth that is associated to the site based on an entity uniquely identified in the server or , providing the geographic address (textual description)  and the geographic location (geometry description) of the physical place

geographicLocation

Yes if address not included

A geo location (GeographicLocation) passed by reference or by value. A GeoLocation allows describing through coordinate(s) a point, a line or a space.

calendar

No

A list of calendar period entries (CalendarPeriod[*]) indicating the time availability of the site for different periods

relatedParty

No

A list of related party references (RelatedPartyRef [*]). A related party defines party or party role linked to a specific entity

siteRelationship

No

A list of site relationships (SiteRelationship [*]).

Linked sites

@baseType

No

A string. Indicates the base type of the resource for extensibility and polymorphism purposes to differentiate the definition of different type of sites (enterprise, residential, …).

@type

No

A string. Indicates the type of the resource for extensibility purposes.

@schemaLocation

No

A string. A Link to the schema describing this REST Resource.

 

 

 

 

GeographicAddress   sub-resource

Address reference. Defines an address and/or identifies an existing address entity

An address allows textual description of an existing place over the surface of the Earth

This resource could be invoked as reference or value

Field

Mandatory in API messages

Description

id

No

A string. Unique identifier of the entity within the server

href

No

A string. Reference of the entity

streetNr

Yes if neither id nor href nor are included

A string. Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses.

streetNrSuffix

No

A string. the first street number suffix.

streetNrLast

No

A string. Last number in a range of street numbers allocated to a property.

streetNrLastSuffix

No

A string. Last street number suffix for a ranged address.

streetName

Yes if neither id nor href nor are included

A string. Name of the street or other street type.

streetType

Yes if neither id nor href nor are included

A string. Alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf.

streetSuffix

No

A string. A modifier denoting a relative direction.

postcode

Yes if neither id nor href nor are included

A string. Descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also known as zipcode).

locality

Yes if neither id nor href nor are included

A string. "An area of defined or undefined boundaries within a local authority or other legislatively defined area, usually rural or semi-rural in nature." [ANZLIC-STREET], or a suburb "a bounded locality within a city, town or shire principally of urban character " [ANZLICSTREET].

city

No

A string. City that the address is in.

stateOrProvince

Yes if neither id nor href nor are included

A string. the State or Province that the address is in.

country

Yes if neither id nor href nor are included

A string. Country that the address is in.

geographicLocation

No

A geo location (GeographicLocation) passed by reference or by value. A GeoLocation allows describing through coordinate(s) a point, a line or a space.

geographicSubAddress

No

A list of sub addresses (GeographicSubAddress [*]). Representation of a SubAddress
It is used for addressing within a property in an urban area (country properties are often defined differently). It may refer to a building, a building cluster, or a floor of a multistory building.

@type

No

A string. Indicates the type of the resource. Here can be 'UrbanPropertyAddress', ‘FormattedAddress’, ‘JapanesePropertyAddress’ , ‘AustralianPropertyAddress’, etc…

@schemaLocation

No

A string. A Link to the schema describing this REST Resource. The resource described 'UrbanPropertyAddress' but a schema could be used for other property address description.

 

GeoGraphicLocation sub-resource

GeographicLocation reference. Defines a geo location and/or identifies an existing geo location entity

A GeoLocation allows describing through coordinate(s) a point, a line or a space.

This resource could be invoked as reference or value

Field

Mandatory in API messages

Description

id

No

A string. Unique Identifier of a GeoLocation.

href

No

A string. href of the GeoLocation.

name

No

A string. Name of a GeoLocation.

type

Yes if href not included

A string. Type allows describing Geolocation form: it could be a point, a line, a polygon, a cylinder, etc....

geographicPoint

Yes if href not included

A list of geo points (GeographicPoint [*]). A GeoPoint defines a geographic point through coordinates.

@type

No

A string. Indicates the type of the resource for extensibility purposes.

@schemaLocation

No

A string. A Link to the schema describing this REST Resource.

 

GeographicPoint sub-resource

A GeoPoint defines a geographic point through coordinates.

Field

Mandatory in API messages

Description

accuracy

Yes

A string. Accuracy of the coordinate specified.

spatialRef

Yes

A string. Geocoding referential.

x

Yes

A string. x coordinate (usually latitude).

y

Yes

A string. y coordinate (usually longitude).

z

No

A string. z coordinate (usually elevation).

 

GeographicSubAddress sub-resource

Representation of a SubAddress
It is used for addressing within a property in an urban area (country properties are often defined differently). It may refer to a building, a building cluster, or a floor of a multistory building.

Field

Mandatory in API messages

Description

id

No

A string. Unique Identifier of the subAddress.

href

No

A string. Href of the subAddress.

type

No

A string. type of subAddress : it can be a subunit or a private street.

name

No

A string. Name of the subAddress to identify it with a meaningful identification.

subUnitType

No

A string. the type of subunit
e.g.BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF.

subUnitNumber

No

A string. the discriminator used for the subunit
often just a simple number e.g. FLAT 5, may also be a range.

levelType

No

A string. describes level types within a building.

levelNumber

No

A string. used where a level type may be repeated e.g. BASEMENT 1, BASEMENT 2.

buildingName

No

A string. allows for buildings that have well-known names.

privateStreetName

No

A string. private streets internal to a property (e.g. a university) may have internal names that are not recorded by the land title office.

privateStreetNumber

No

A string. private streets numbers internal to a private street.

@type

No

A string. Type of the resource for thus subResource

@schemaLocation

No

A string. A Link to the schema describing the structure of this REST Resource to allow for extensions

 

RelatedPartyRef   relationship

Field

Mandatory in API messages

Description

id

Yes

A string. Unique identifier of the entity within the server

href

No

A string. Reference of the entity

name

No

A string. Name of the related party

role

No

A string. Role of the related party

validFor

No

TimeperiodType. Validity for the relationship with the related party

@type

No

A string. Indicates the type of the resource. Here can be 'Individual', ‘Organization’, etc…

 

SiteRelationship   relationship

Field

Mandatory in API messages

Description

id

Yes

A string. Unique identifier of the related site entity within the server

href

No

A string. Reference of the related site

type

Yes

A string. Type of relationship

role

No

A string. Role of the related site in the relationship

validFor

No

TimePeriodType. Validity for the relationship

 

CalendarPeriod sub-resource

Field

Mandatory in API messages

Description

status

Yes

A string. Indication of the availability of the site (e.g.: open)

day

Yes

A string. Day where the calendar status applies (e.g.: monday, mon-to-fri, weekdays, weekend, all week, …)

timeZone

No

A string. Indication of the timezone applicable to the calendar information (e.g.: Paris, GMT+1)

hourPeriod

Yes

A list of periods of hours (HourPeriod [*]). Defines the time period when the status for the place is applicable

 

HourPeriod type

Field

Mandatory in API messages

Description

startHour

Yes

A string. The time when the status starts applying

endHour

Yes

A string. The time when the status ends applying

 

 

Json representation sample

The example below provides the json representation of a 'GeographicSite' resource object (including main elements) where the physical place associated is included via reference to an address entity registered in the server

{
    "id": "12345",
    "href": "https://host:port/siteManagementlocation/v1/site/12345",
    "name": "Main Building",

    "description": "This site refers to the Main Building of the company",

    "status": "active",

     "address": {
        "id": "9912",
        "href": " https://host:port/addressManagement/v1/address/9912"
     },
     "calendar": [{
        "status": "open",
        "day": "weekdays",
        "timeZone": "GMT+1",
        "hourPeriod": [
                {
                    "startHour": "9:00 am ",
                    "endHour": "18:00  pm"
                }
     }],

     "siteRelationship": [{
        "id": "9913",
        "href": " https://host:port/addressManagement/v1/address/9913",

        "type": "alternative site",
        "role": "emergency available office"
     }]
}

 

The example below provides the json representation of a 'GeographicSite' resource object (including main elements) where the physical place associated is included directly, providing all the geographic address and geolocation information

{
    "id": "12345",
    "href": "https://host:port/siteManagementlocation/v1/site/12345",
    "name": "Main Building",

    "description": "This site refers to the Main Building of the company",

    "status": "active",

     "address": {
        "streetNr": "56",
        "streetName": "Arlington",
        "streetType": "Road",
        "postcode": "W45E02",
        "locality": "London",
        "city": "London",
        "stateOrProvince": "Great London",
        "country": "England",

        "geographicLocation": {
            "type": "point",
            "geographicPoint": [
                {
                    "accuracy": "",
                    "spatialRef": "WGS84",
                    "x": " 1.430937",
                    "y": " 43.597208",
                    "z": ""
                }
            ]

       }
     },
     "calendar": [{
        "status": "open",
        "day": "weekdays",
        "timeZone": "GMT+1",
        "hourPeriod": [
                {
                    "startHour": "9:00 am ",
                    "endHour": "18:00  pm"
                }
     }],

     "siteRelationship": [{
        "id": "9913",
        "href": " https://host:port/addressManagement/v1/address/9913",

        "type": "alternative site",
        "role": "emergency available office"
     }]
}

 

The example below provides the json representation of a 'GeographicSite' resource object (including main elements) where the physical place associated is included via reference to a geographical location entity registered in the server and also associated at creation to an specific party (organization)

{
    "id": "12345",
    "href": "https://host:port/siteManagementlocation/v1/site/12345",
    "name": "Main Building",

    "description": "This site refers to the Main Building of the company (organization XYZ)",

    "status": "planned",

     " geographicLocation ": {
        "id": "geo001",
        "href": " https://host:port/ geographicLocationManagement/v1/geographicLocation /geo001"
     },
     "calendar": [{
        "status": "open",
        "day": "weekdays",
        "timeZone": "GMT+1",
        "hourPeriod": [
                {
                    "startHour": "9:00 am ",
                    "endHour": "18:00  pm"
                }
     }],

     "relatedParty": [{
        "id": "1234",
        "href": " https://host:port/partyManagement/organization/1234",

        "name": "organizationXYZ",
        "role": "headquarters" ,

        "@type": "organization",
     }]
}

 

 

 

Notification Resource Models

2 notifications are defined for this API

Notifications related to GeographicSite:
    - GeographicSiteCreationNotification
    - GeographicSiteChangeNotification
 

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification resource (depicted by "SpecificNotification" placeholder) is a sub class of a generic Notification structure containing an id of the event occurrence (eventId), an event timestamp (eventTime), and the name of the notification resource (eventType).
This notification structure owns an event structure ("SpecificEvent" placeholder) linked to the resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

 

GeographicSite Creation Notification

Notification sent when a new GeographicSite resource is created.

Json representation sample

We provide below the json representation of an example of an 'GeographicSiteCreationNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"GeographicSiteCreationNotification",
     "event": {
        "geographicSite" :
            {-- SEE GeographicSite RESOURCE SAMPLE --}
    }
}
 

 

 

 

GeographicSite Change Notification

Notification sent when a new GeographicSite resource is modified.

Json representation sample

We provide below the json representation of an example of an 'GeographicSiteModificationNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"GeographicSiteModificationNotification",
     "event": {
        "geographicSite" :
            {-- SEE GeographicSite RESOURCE SAMPLE --}
    }
}
 

 

API OPERATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample REST requests and responses.

Remember that the following Uniform Contract rules must be used:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

 

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

For reconciliation processes

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

 

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.

 

Operations on Geographicsite

List sites

  GET /geographicSiteManagement/v1/geographicSite?{fields=attributes}&{filtering expression}

Description

The Application invokes this operation to retrieve a list of sites stored in the server.

 

The request could include filters in order to retrieve only a specific subset of all the sites stored in the server such as filtering by status.

 

At least one filter is expected in order to prevent from having a response to an unbounded collection but each specific server and application must define the limits on the maximum number of elements in the response

 

Behavior:

Status Code

Description

200

List of Sites information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

Usage Samples

The example below includes the attributes within the Sites resource model that must be included in the query response

REQUEST

GET https://{serverRoot}/geographicSiteManagement/v1/geographicSite 

Accept: application/json

RESPONSE

200

Content-Type: application/json

[

{

    "id": "12345",
    "href": "https://host:port/geographicSiteManagement/v1/geographicSite/12345",
    "name": "Main Building",

    "description": "This site refers to the Main Building of the company",

    "status": "active",

     "address": {
        "id": "9912",
        "href": " https://host:port/ geographicAddressManagement/v1/ geographicAddress/9912"
     },
     "calendar": [{
        "status": "open",
        "day": "weekdays",
        "timeZone": "GMT+1",
        "hourPeriod": [
                {
                    "startHour": "9:00 am ",
                    "endHour": "18:00  pm"
                }
     }]

},

{

    "id": "9876",
    "href": "https://host:port/ geographicSiteManagement /v1/geographicSite/9876",
    "name": "Second Building",

    "description": "This site refers to the Second Building of the company, open in weekends",

    "status": "active",

     "address": {
        "streetNr": "60",
        "streetName": "Arlington",
        "streetType": "Road",

        "postcode": "W45E02",
        "locality": "London",
        "stateOrProvince": "Great London",
        "country": "England",

       }
     },
     "calendar": [{
        "status": "open",
        "day": "weekends",
        "timeZone": "GMT+1",
        "hourPeriod": [
                {
                    "startHour": "9:00 am ",
                    "endHour": "13:00  pm"
                }
     }]

}

]

 

Register new site

  POST /geographicSiteManagement/v1/geographicSite

Description

The Application invokes this operation to request a new geopgraphicSite resorce to be created in tehs erver

Behavior:

Status Code

Description

201

Successful site registration (resource created)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

Mandatory and Non Mandatory Attributes

The following tables provides the list of mandatory and non mandatory attributes when creating a RetrieveGeographicLocation, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

address

Required if geographicLocation not included

geographicLocation

required if address not included

 

Non Mandatory Attributes

Default Value

Rule

description

 

 

code

 

 

status

 

 

calendar

 

 

relatedParty

 

 

siteRelationship

 

 

 

 

Usage Samples

The example below includes the attributes within the GeographicSite entity resource model that are mandatory to be included in the request when creating a new resource in the server when associating an address to a site

REQUEST

POST https://{serverRoot}/geographicSiteManagement/v1/geographicSite

Content-type: application/json

{

    "name": "New branch to be open in France ",

    "description": "This site refers to the new branch office to be open in France",

    "status": "planned",

     "address": {
        "streetNr": "1",
        "streetName": "République (de la)",
        "streetType": "Rue",

        "postcode": "13001",
        "locality": "Marseille",
        "stateOrProvince": "Bouches-du-Rhône",
        "country": "France",

     }

}

RESPONSE

201

Content-Type: application/json

Location: https://{serverRoot}/geographicSiteManagement/v1/geographicSite/12345

 

 

Response is not required to include a BODY with the contents of the geographicSite resource created, but if included it must be filled with at least the mandatory parameters.

 

The example below includes the attributes within the GeographicSite entity resource model that are mandatory to be included in the request when creating a new resource in the server when associating a geographic location to a site for an specific party (organization)

REQUEST

POST https://{serverRoot}/geographicSiteManagement/v1/geographicSite

Content-type: application/json

{

    "name": "New branch to be open in France ",

    "description": "This site refers to the new branch office to be open in France",

    "status": "planned",

     "address": {
        "streetNr": "1",
        "streetName": "République (de la)",
        "streetType": "Rue",

        "postcode": "13001",
        "locality": "Marseille",
        "stateOrProvince": "Bouches-du-Rhône",
        "country": "France",

     },

                    "relatedParty": [{
                         "id": "1234",
                         "href": " https://host:port/partyManagement/organization/1234",

                          "name": "organizationXYZ",
                          "role": "headquarters" ,

          "@type": "organization",
     }]
 

}

RESPONSE

201

Content-Type: application/json

Location: https://{serverRoot}/geographicSiteManagement/v1/geographicSite/12345

 

 

Response is not required to include a BODY with the contents of the geographicSite resource created, but if included it must be filled with at least the mandatory parameters.

 

 

Retrieve individual site

  GET /geographicSiteManagement/v1/geographicSite/{siteId}?{fields=attribs}

Description

This operation retrieves a site entity using its unique ID. This ID should be retrieve either using the site creation process, or in another API of the ecosystem (party, appointment, etc.)
 

Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Behavior:

Status Code

Description

200

the site information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

Usage Samples

The example below includes the attributes within the GeographicSite resource model that must be included in the query response where the physical place associated is included via reference to an address entity regoistered in the server

REQUEST

GET https://{serverRoot}/geographicSiteManagement/v1/geographicSite/12345 

Accept: application/json

RESPONSE

200

Content-Type: application/json

{

    "id": "12345",
    "href": "https://host:port/geographicSiteManagement/v1/geographicSite/12345",
    "name": "Main Building",

    "status": "active",

     "address": {
        "id": "9912",
        "href": " https://host:port/geographicAddressManagement/v1/geographicAddress/9912"
     }
}

 

 

The example below includes the attributes within the GeographicSite resource model that must be included in the query response where the physical place associated is included directly, providing all the gepgraphic address and geolocation information

REQUEST

GET https://{serverRoot}/geographicSiteManagement/v1/geographicSite/12345 

Accept: application/json

RESPONSE

200

Content-Type: application/json

{

    "id": "12345",
    "href": "https://host:port/geographicSiteManagement/v1/geographicSite/12345",
    "name": "Main Building",

    "status": "active",

     "address": {
        "streetNr": "56",
        "streetName": "Arlington",

        "streetType": "Road",
        "postcode": "W45E02",

        "locality": "London",
        "stateOrProvince": "Great London",
        "country": "England",
     }
}

 

 

Complete update of an individual site

  PUT /geographicSiteManagement/v1/geographicSite/{siteId}

Description

This operation is optional to be supported in this API

This operation updates completely the ocntents of a geographicSite resource by replacing the contents of that entity with the contents of the resource structure provided in the request.

Notice that the PUT method is intended to modify completely the resource impacted, meaning that optional values that are not included in the request may be erased in the server after updating, and will not keep the previous value stored. Behaviour of the server on optional valuesnot included is undefined.


 

Behavior:

Status Code

Description

200

Successful site modification (resource updated)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

Usage Samples

The example below includes the attributes within the GeographicSite entity resource model that are mandatory to be included in the request when updating completely a resource in the server

REQUEST

PUT https://{serverRoot}/geographicSiteManagement/v1/geographicSite/12345 

Content-type: application/json

{

    "name": "New branch open in France ",

    "description": "This site refers to the new branch office recently open in France",

    "status": "active",

     "address": {
        "streetNr": "1",
        "streetName": "République (de la)",
        "streetType": "Rue",

        "postcode": "13001",
        "locality": "Marseille",
        "stateOrProvince": "Bouches-du-Rhône",
        "country": "France",

     }

}

RESPONSE

200

Content-Type: application/json

 

 

Response is not required to include a BODY with the contents of the GeographicSite resource created, but if included it must be filled with the new values set and include at least the mandatory parameters (including id and href).

 

 

Partial update of an individual site

  PATCH /geographicSiteManagement/v1/geographicSite/{siteId}

Description

This operation is optional to be supported in this API

This operation allows partial updates of a geographicSite resource entity. The definition of the modification is recommended to follow the json/patch ( http://tools.ietf.org/html/rfc5789 ) and the extension proposed in Design Guidelines to manage modification of array entities.

 

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their usage.

Patchable attributes

Rule

name

 

description

 

code

 

status

 

addressRef

 

address

 

calendar

 

relatedParty

 

siteRelationship

 

 

Non Patchable attributes

Rule

id

 

href

 

 

Behavior:

Status Code

Description

200

Successful site modification (resource modified)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

Usage Samples

The example below shows how to complete a partial update os a GeographicSite entity resource model using the the json/patch (RFC5789) approach

To Be Completed

 

Delete an individual site

  DELETE /geographicSiteManagement/v1/geographicSite/{siteId}

Description

This operation is optional to be supported in this API

Note: this operation is available only to ADMIN API users

This operation deletes and removes from the server geographicSite resource previously registered.

 

Behavior:

Status Code

Description

204

Successful site removal

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

Usage Samples

The example below shows a request for deleting a GeographicSite resource

REQUEST

DELETE https://{serverRoot}/geographicSiteManagement/v1/geographicSite/12345 

 

RESPONSE

204

 

 

 

API NOTIFICATIONS

For every single of operation on the entities use the following templates and provide sample REST notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST Guidelines reproduced below.

Register listener

  POST /hub

Description

Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint can be created again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.

 


Request
 

POST /api/hub

Accept: application/json

 

{"callback": "http://in.listener.com"}
 


Response
 

201

Content-Type: application/json

Location: /api/hub/42

 

{"id":"42","callback":"http://in.listener.com","query":null}

 

 

Unregister listener

  DELETE /hub/{id}

Description

Clears the communication endpoint address that was set by creating the Hub..

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.


Request
 

DELETE /api/hub/42

Accept: application/json
 


Response
 

204

 

Publish Event to listener

  POST /client/listener

Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener url is the callback url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be replaced by one of the notification types supported by this API (see Notification resources Models section) and EVENT BODY refers to the data structure of the given notification type.


Request
 

POST /client/listener

Accept: application/json

 

{

    "event": {

                EVENT BODY

            },

    "eventType": "EVENT_TYPE"

}
 


Response
 

201

 

For detailed examples on the general TM Forum notification mechanism, see the TMF REST Design Guidelines.

 


Acknowledgements

 

Release History

Release Number

Date

Release led by:

Description

Release 1.0-1

22/05/2017

Luis Velarde (Telefónica)

First Release of Draft Version of the Document.

Release 1.0-2

24/10/2017

Luis Velarde(Telefónica)

Updated to be aligned with TMF API guidelines 3.0

Updated after review comments in R17.5 (October review cycle)

 

 

Contributors to Document

Luis Velarde

Guillermo Martínez

Telefonica

Mariano Belaunde

Maxime Delon

Ludovic Robert

Orange

Nicoleta Stoica

Vodafone

Dirk Rejahl

Bearing Point

Pierre Gauthier

TM Forum