Page tree

 

 

 

 

 

 

 

Geographic Site Management API
Conformance Profile

 

Document Number TMF674B

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

API DESCRIPTION

RESOURCE MODEL CONFORMANCE

GepgraphicSite Management API MANDATORY AND OPTIONAL RESOURCES

GeographicSite resource MANDATORY AND OPTIONAL ATTRIBUTES

API OPERATIONS CONFORMANCE

GeographicSite MANDATORY AND OPTIONAL OPERATIONS

API GET FILTERING OPERATION CONFORMANCE

Filtering in GeographicSite resource

GET /geographicSiteManagement /v1/geographicSite

GET /geographicSiteManagement /v1/geographicSite /{siteId}

API POST OPERATION CONFORMANCE

POST /geographicSiteManagement /v1/geographicSite

API PUT OPERATION CONFORMANCE

API PATCH OPERATION CONFORMANCE

API DELETE OPERATION CONFORMANCE

API CONFORMANCE TEST SCENARIOS

GeographicSite resource TEST CASES

 

List of Tables

 

 

Introduction

The following document is the REST API Conformance for the GeographicSite Management API.

API DESCRIPTION

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 (geographic 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

RESOURCE MODEL CONFORMANCE

GepgraphicSite Management API MANDATORY AND OPTIONAL RESOURCES

 

Resource Name

Mandatory or Optional

Comments

GeographicSite

M

 

 

 

GeographicSite resource MANDATORY AND OPTIONAL ATTRIBUTES

Attribute Name

Mandatory or Optional

Comments

id

M in response messages

O otherwise

Only valid in request if the server allows the client to define the id for the resource to be created

href

M in response messages

O otherwise

 

name

M

 

 

description

O

 

code

O

 

Status

M in response messages

O otherwise

 

address

M if geographicLocation not included at first level

 

 

id

O

 

 

href

O

 

 

streetNr

M if neither address.id nor address.href are included

 

 

streetNrSuffix

O

 

 

streetNrLast

O

 

 

streetNrLastSuffix

O

 

 

streetName

M if neither address.id nor address.href are included

 

 

streetType

M if neither address.id nor address.href are included

 

 

streetSuffix

O

 

 

postcode

M if neither address.id nor address.href are included

 

 

locality

M if neither address.id nor address.href are included

 

 

city

O

 

 

stateOrProvince

M if neither address.id nor address.href are included

 

 

country

M if neither address.id nor address.href are included

 

 

geographicLocation

O

 

 

 

id

O

 

 

 

href

O

 

 

 

name

O

 

 

 

type

M if neither address.geographicLocation.id nor address.geographicLocation.href are included

 

 

 

geographicPoint

M if neither address.geographicLocation.id nor address.geographicLocation.href are included

Array of structures including at least one entity

 

 

 

accuracy

M if geographicPoint included

 

 

 

 

spatialRef

M if geographicPoint included

 

 

 

 

x

M if geographicPoint included

 

 

 

 

y

M if geographicPoint included

 

 

 

 

z

O

 

 

geographicSubAddress

O

Array of structures including at least one entity

 

 

id

O

 

 

 

href

O

 

 

 

type

O

 

 

 

name

O

 

 

 

subUnitType

O

 

 

 

subUnitNumber

O

 

 

 

levelType

O

 

 

 

levelNumber

O

 

 

 

buildingName

O

 

 

 

privateStreetName

O

 

 

 

privateStreetNumber

O

 

geographicLocation

M if address not included at first level

 

 

id

O

 

 

href

O

 

 

name

O

 

 

type

M if neither geographicLocation.id nor geographicLocation.href are included

 

 

geographicPoint

M if neither geographicLocation.id nor geographicLocation.href are included

Array of structures including at least one entity

calendar

O

 

 

status

M if calendar included

 

 

day

M if calendar included

 

 

timeZone

O

 

 

hourPeriod

M if calendar included

 

 

 

startHour

M if hourPeriod included

 

 

 

endHour

M if hourPeriod included

 

relatedParty

O

 

 

id

M If relatedParty included

 

 

href

O

 

 

name

O

 

 

role

O

 

 

validFor

O

 

siteRelationship

O

 

 

id

M if siteRelationship included

 

 

href

O

 

 

type

M if siteRelationship included

 

 

role

O

 

 

validFor

O

 

 

API OPERATIONS CONFORMANCE

For every single resource use the following templates and define what operations are optional and what operations are mandatory.

GeographicSite MANDATORY AND OPTIONAL OPERATIONS

 

Uniform API Operation

Mandatory/Optional

Comments

GET

M

GET must be used to retrieve a representation of a resource

 

POST

M

POST must be used to create a new resource

PUT

O

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

PATCH

O

PATCH must be used to partially update a resource

DELETE

O

DELETE must be used to remove a resource

 

 

 

 

API GET FILTERING OPERATION CONFORMANCE

Definitions

 

Filtered Search: A filtered search can be applied using query parameters in order to obtain only the resource entities that meet the criteria defined by the filtering parameters included in the query request. Several elements can be applied to the filtered search. In that case logic, a logical AND is applied to combine the criteria (e.g.:?name=<value> &owner.id=<value>)

 

Filtered Response Data (Response Attribute selection): In order to apply a filter and limit the number of attributes included in the response, the GET request can include the “ ?fields=” query parameter. Several elements can be applied to the filter. In that case, a logical AND is applied to combine the values (e.g.:?fields=name,description will provide in the response only the values assigned to attributes name and description). Attribute selection capabilities are the same for collections retrieval and individual resource queries

 

Filtering in GeographicSite resource

Attribute name

Filtered search

First Level

Filtered search

N Level

Response Attribute Selection

First Level

Response Attribute Selection

N Level

id

NA

NA

M

NA

href

NA

NA

M

NA

name

O

NA

M

NA

description

NA

NA

M

NA

code

O

NA

M

NA

status

O

O

M

O

address

NA

O

(id)

(streetNr)

(streetName)

(streetType)

(postcode)

(locality)

(stateOrProvince)

M

NA

address.geographicLocation

NA

O

(id)

(name)

NA

NA

geographicLocation

NA

O

(id)

(name)

NA

NA

calendar

NA

NA

M

NA

relatedParty

NA

O

(id)

(name)

(role)

M

NA

siteRelationship

NA

O

(id)

(type)

(role)

M

NA

 

 

GET /geographicSiteManagement /v1/geographicSite

 

Filtered Search: A filtered search can be applied using the following filtering criteria

 

  • code: to obtain the sites assigned a given code

 

  • status: to obtain the sites in a given status

 

  • address.id: to obtain the sites referenced by a given address identified by id

 

  • address.streetNr: to obtain the sites located in a given street number. This is typically used together with other filter such as streetName

 

  • address.streetName: to obtain the sites located in a given street number. This is typically used together with other filter such as streetNr

 

  • address.streetType: to obtain the sites located in a given street type

 

  • address.postcode: to obtain the sites witha given postcode

 

  • address.locality: to obtain the sites located in a given locality. This is typically used together with other filter such as streetName

 

  • address.stateOrProvince: to obtain the sites located in a given state/province. This is typically used together with other filter such as streetName and locality

 

  • address.geographicLocation.id: to obtain the sites located in a given location (linked to an an address) identified by id

 

  • address.geographicLocation.name: to obtain the sites located in a given location (linked to an an address) identified by name

 

  • geographicLocation.id: to obtain the sites located in a given location identified by id

 

  • geographicLocation.name: to obtain the sites located in a given location identified by name

 

  • relatedParty.id: to obtain the sites related to a given party identified by id

 

  • relatedParty.name: to obtain the sites related to a given party identified by name

 

  • relatedParty.role: to obtain the sites related to a given party with a given role

 

  • siteRelationship.id: to obtain the sites related to another site identified by id

 

  • siteRelationship.type: to obtain the sites related to another site with a given type of relationship

 

  • siteRelationship.role: to obtain the sites related to another site with a given role in teh relationship

 

 

 

Filtered Response Data: A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of GeographicSite resource definition

 

 

GET /geographicSiteManagement /v1/geographicSite /{siteId}

Filtered Response Data: A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of GeographicSite resource definition

API POST OPERATION CONFORMANCE

 

POST /geographicSiteManagement /v1/ geographicSite

This Uniform Contract operation is used to create a GeographicSite resource in the server.

The response to this operation must include a Location header set to /geographicSiteManagement /v1/geographicSite {siteId} where {siteId} indicates the identifier assigned by the server to the new GeographicSite resource created

POST

M

 

Response Status Code 201

M

 

Other Status Codes

NA

 

 

 

The following table indicates attributes that are required to be sent when creating a new GeographicSite resource defined by an address as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the BODY of the POST request message:

Attribute name

Mandatory

Default

Rule

name

Y

 

 

address

Y

 

 

address.id

N

 

Mandatory if address is passed by reference and no address.href is provided

address.href

N

 

Mandatory if address is passed by reference and no address.id is provided

address.streetNr

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

address.streetName

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

address.streetType

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

address.postcode

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

address.locality

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

address.stateOrProvince

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

address.country

N

 

Mandatory if address is passed by value (if neither address.id nor address.href are included)

 

The response from the server may optionally include a BODY with the contents of the new resource created

If the POST request includes optional parameters (as per the model resource definition) that are not supported by the server, then the server must reject the request (replying with a 4xx error response) indicating the parameter not supported.

The following parameters must be supported by the server when included in the request to create a new resource

  • name
  • description
  • code
  • status
  • address and all the attributes defined in the resource model
  • calendar and all the attributes defined in the resource model
  • relatedParty and all the attributes defined in the resource model
  • siteRelationship and all the attributes defined in the resource model

 

The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

The BODY of the response from the server must include the following attributes that are mandatory in the definition of a GeographicSite as per the resource model defined even if they are not included in the request

  • id
  • href
  • status

API PUT OPERATION CONFORMANCE

This Uniform Contract operation is used to completely update a GeographicSite resource existing in the server.

Since PUT operation is optional and not included in the basic CONNECT certification this is not applicable in this conformance document.

API PATCH OPERATION CONFORMANCE

This section defines which attributes are patchable.

Since PATCH operation is optional and not included in the basic CONNECT certification this is not applicable in this conformance document.

API DELETE OPERATION CONFORMANCE

This section defines what operations can be used to delete a GeographicSite resource.

 

Since DELETE operation is optional and not included in the basic CONNECT certification this is not applicable in this conformance document

 

 

API CONFORMANCE TEST SCENARIOS

This section describes the test scenarios required for the basic CONNECT certification of GeographicSite Management API. These test scenarios cover the management of sites linked to an address, leaving as optional the support of sites linked to a geographic location.

Test Cases must be executed in the order defined for each resource because the result from one of the scenarios will be input for the next one.

Requests must be addressed to the endpoint provided for certification, specifically they must be addressed to the URI defined by the concatenation of the {apiRoot} and the specific resource, where the {apiRoot} is defined as {serverRoot}/geographicSiteManagement /v1 , being {serverRoot} the certification endpoint

 

GeographicSite resource TEST CASES

Nominal Scenarios

TC_GeoSite_N1 – Create new single site

  • Send a POST message to {apiRoot}/geographicSite/ with the following contents in the BODY

{

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

    "description": "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",

     }

}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to {apiRoot}/geographicSite/{Site01} where {Site01} indicates the identifier assigned by the server to the new GeographicSite resource

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values in the original request

 

  • Send a GET message to /{apiRoot}/geographicSite/

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one GeographicSite resource with ID set to {Site01}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {Site01} matches the values in the original request

 

  • Send a GET message to /{apiRoot}/geographicSite/{Site01}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The response message includes all mandatory parameters

 

-           The body of the response includes a GeographicSite resource structure that matches the values in the original request

 

TC_ GeoSite _N2 – Search for site with specific characteristics

  • Send a POST message to {apiRoot}/geographicSite/ with the following contents in the BODY

{

    "name": "Existing site, headquarters",

    "description": "Refers to a site in an existing address registered",

    "address": {

        "id": "9912",

        "href": "host:port/ geographicAddressManagement/v1/geographicAddress/9912 ",

     },

     "calendar": [{

        "status": "open",

        "day": "weekdays",

        "timeZone": "GMT+1",

        "hourPeriod": [

                {

                    "startHour": "9:00 am ",

                    "endHour": "18:00  pm"

                }

     }]

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to {apiRoot}/geographicSite/{Site02} where {Site02} indicates the identifier assigned by the server to the new Permission resource

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values in the original request

 

  • Send a GET message to /{apiRoot}/geographicSite

 

  • Wait for a response from the server with the following characteristics

-           Response Code 200-OK

 

-           The body of the response includes two geographicSite resources, referring to {Site01} and {Site02}

 

-           The body of the response for the resource with each identifier matches the values in the corresponding original request

 

  • Send a GET message to /{apiRoot}/geographicSite/?status=planned

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one GeographicSite resource, referring to {Site01}

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {Site01} matches the values in the original request

 

  • Send a GET message to /{apiRoot}/geographicSite/?address.id=9912

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one Permission resource, referring to {Site02}

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {Site02} matches the values in the original request

 

TC_GeoSite_N3 – Filtered retrieval of site data

  • Send a GET message to /{apiRoot}/geographicSite/{Site01}?fields=name,status

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one GeographicSite resource, referring to {Site01} and including only attributes name and status , matching the values in the original request

 

  • Send a GET message to /{apiRoot}/geographicSite/{Site02}?fields=id,calendar

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one GeographicSite resource, referring to {Site02} and including only attributes id and calendar , matching the values in the original request

Notice that this test case is using parameters ” name”, ”status”, ”id” and ”calendar”  to filter the data included in the response  but any other parameter could be used

 

TC_GeoSite_N4 – Filtered Search and Filtered data response

  • Send a GET message to /{apiRoot}/geographicSite/?address.id=9912&fields= calendar

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one geographicSite resource, referring to {Site02}

 

-           The body of the response for the resource with each identifier includes only attribute calendar , matching the values in the corresponding original request

Notice that this test case is using parameters ”calendar” t o filter the data included in the response  but any other parameter could be used

 

TC_GeoSite_N5 – Parameter not included in site creation request but provided in response

  • Send a POST message to {apiRoot}/geographicSite/ with the following contents in the BODY

 

{

    "name": "Second Building",

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

     "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"

                }

     }]

}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body including the identifier assigned by the server to the new Permission resource

 

-           The body of the response includes parameters ”id” , ”href” and ”status”

 

Error Scenarios

TC_GeoSite_E1 – Unknown Site

  • Send a GET message to /{apiRoot}/geographicSite/{Site04}, where {Site04} does not match any of the identifiers previously creted in the server

 

  • Wait for a response from the server with the following characteristics

 

  • Response Code 404-Not Found

 

TC_GeoSite_E2 – Invalid Request – Missing mandatory parameter

  • Send a POST message to {apiRoot}/geographicSite/ with the following contents in the BODY.

 

{

    "description": "Refers to the new branch office to be open in France",

     "address": {

        "streetNr": "1",

        "streetName": "République (de la)",

        "streetType": "Rue",

        "postcode": "13001",

        "locality": "Marseille",

        "stateOrProvince": "Bouches-du-Rhône",

        "country": "France",

     }

}

 

 

Notice that this request is missing mandatory parameter ”name” but any other mandatory parameter could be used

 

  • Wait for an error response from the server indicating the mandatory parameter is missing in the request

 

TC_GeoSite_E3 – Invalid Request – Missing parameter mandatory in context

  • Send a POST message to {apiRoot}/geographicSite/ with the following contents in the BODY.

{

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

    "description": "Refers to the new branch office to be open in France",

     "address": {

        "streetNr": "1",

        "streetName": "République (de la)",

        "streetType": "Rue",

        "postcode": "13001",

        "stateOrProvince": "Bouches-du-Rhône",

        "country": "France",

     }

}

 

Notice that this request is missing mandatory parameter “ streetName ” when parameter “ address” is included but any other parameter that becomes mandatory based on the context could be used

 

  • Wait for an error response from the server indicating the mandatory parameter is missing in the request