Page tree

 

Shopping Cart API CONFORMANCE

 

Document Number:  <###>

Document Version: : <V#.#>

Date:  2017 .03.26

Document Status: Draft

NOTICE

Copyright © TeleManagement Forum 201 7 . 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:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

API DESCRIPTION

RESOURCE MODEL CONFORMANCE

Shopping Cart API MANDATORY AND OPTIONAL RESOURCES

Shopping Cart R esource MANDATORY AND OPTIONAL ATTRIBUTES

API OPERATIONS CONFORMANCE

Shopping Cart MANDATORY AND OPTIONAL OPERATIONS

API GET FILTERING OPERATION CONFORMANCE

Filtering in shopping cart resource

GET / shoppingCart /{ID} ??fields=...&{filtering}

API POST OPERATION CONFORMANCE

POST to / shoppingCart

API PATCH OPERATION CONFORMANCE

API DELETE OPERATION CONFORMANCE

API CONFORMANCE TEST SCENARIOS

Shopping Cart resource TEST CASES

 

List of Tables

 

 

Introduction

The following document is the REST API Conformance for the Shopping Cart API.

API DESCRIPTION

The Shopping Cart API provides the standardized mechanisms for shopping operation such as creation, update, retrieval and deletion of these entities.

The operations that can be exercised over a shopping cart resource using the API and covered in this document are those identified as mandatory to be supported such as

  • Retrieve details of one specific shopping cart entity (GET)
  • List all the existing shopping cart (GET)
  • Create new shopping cart (POST)
  • Update the existing shopping cart (PATCH)
  • Delete the existing shopping cart (DELETE)

 

 

This document identifies the parameters that must be included in a request related to the operations above as well as the parameters expected in the response.

 

The test scenarios in this document are intended to create a set of resources ( Shopping Cart ) and then retrieve the information stored in the server so as to confirm the resources created are stored with the values originally set. Additionally, some test scenarios are included to verify that the server replies with the corresponding error response in situations where a mandatory attribute is not included in the request.

 

RESOURCE MODEL CONFORMANCE

Shopping Cart API MANDATORY AND OPTIONAL RESOURCES

For the Resources defined by the API, here the following table indicates which are mandatory and which ones are optional.

 

Resource Name

Mandatory or Optional

Comments

ShoppingCart

M

 

 

 

Shopping Cart R esource MANDATORY AND OPTIONAL ATTRIBUTES

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

O (otherwise)

Generated by the server and provided in the response upon resource creation.

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

cartTotalPrice

M

A list of cart prices (CartPrice [*])

cartItem

O

A list of cart items (CartItem [*])

When the shopping cart is not empty, the cart item should be filled.

relatedParty

O

A list of related party references (RelatedPartyRef [*])

It is r equired only for identified party. In case of prospect (guest) the contact medium is  used to identify the shopping cart when returning to the shop (typically e-mail)

 

id

M (if relatedParty included)

O (otherwise)

 

 

href

M (in response messages and if relatedParty included)

O (otherwise)

Only required in response messages from the server

 

role

O

 

 

name

O

 

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

note

O

A list of notes (Note [*])

 

author

O

 

 

date

M

If note is included

 

text

M

If note is included

contactMedium

O

 

 

preferred

M (in response messages and if contactMedium included)

O (otherwise)

Only required in response messages from the server when providing the contactMedium structure contents

 

type

M (if contactMedium included)

O (otherwise)

 

 

medium

M (if contactMedium included)

O (otherwise)

 

 

validFor

O

 

 

 

startDateTime

O

 

 

 

endDateTime

O

 

 

characteristics

O

 

 

 

city

O

 

 

 

country

O

 

 

 

emailAddress

O

 

 

 

faxNumber

O

 

 

 

phoneNumber

O

 

 

 

postCode

O

 

 

 

stateOrProvince

O

 

 

 

street1

O

 

 

 

street2

O

 

 

 

type

O

 

 

 

 

 

In the CartItem sub-resource,

Attribute Name

Mandatory or Optional

Comments

action

O

 

id

M

 

quantity

M

 

status

M

 

car t Item

O

A list of cart items

The s ub cart item s are required only for bundle offering .

totalItemPrice

M

A list of cart prices

product

O

A product ref or value (ProductRefOrValue)

 

href

M

 

 

id

M

 

 

name

M

 

 

productRelationship

O

 

 

 

type

M

 

 

 

product

M

 

 

place

O

 

 

 

address

O

 

 

 

geoLocationUrl

O

 

 

 

href

M

 

 

 

Id

M

 

 

 

role

O

 

 

characteristic

O

 

 

relatedParty

O

 

 

productSpecification

O

 

 

href

M

 

 

id

M

 

 

name

M

 

 

version

O

 

 

p roductCharacteristic

O

 

 

 

name

M

 

 

 

value

M

 

itemPrice

M

 

productOffering

M

 

 

href

M

 

 

id

M

 

 

name

M

 

 

bundledProductOffering

O

 

 

 

href

M

 

 

 

id

M

 

 

 

name

M

 

 

 

bundledProductOffering

M

 

cartItemRelationship

O

 

 

id

M

If cartItemRelationship is included.

 

type

M

If cartItemRelationship is included.

 

cartItem

M

If cartItemRelationship is included.

 

 

 

 

In the CartPrice sub-resource,

Attribute Name

Mandatory or Optional

Comments

description

O

 

name

M

 

priceType

M

 

recurringChargePeriod

O

 

unitOfMeasure

O

 

price

M

 

 

currencyCode

M

 

 

dutyFreeAmount

M

 

 

percentage

O

 

 

taxIncludedAmount

O

 

 

taxRate

O

 

priceAlteration

O

 

 

applicationDuration

O

 

 

description

O

 

 

name

O

 

 

priceType

M

 

 

priority

O

 

 

recurringChargePeriod

O

 

 

unitOfMeasure

O

 

 

price

M

 

 

 

 

 

 

 

API OPERATIONS CONFORMANCE

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

Shopping Cart MANDATORY AND OPTIONAL OPERATIONS

 

Uniform API Operation

Mandatory/Optional

Comments

GET (Retrieve)

M

GET must be used to retrieve a representation of a resource

 

POST

M

POST must be used to create a new resource

GET (List)

O

GET must be used to retrieve a representation of a resource

PATCH

O

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

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.

 

Filtered Data (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.

 

Filtering in shopping cart resource

Attribute name

Filtered search

First Level

Filtered search

N Level

Attribute Selection First Level

Attribute Selection N Level

Id

O

NA

M

NA

href

NA

NA

M

NA

cartTotalPrice

O

NA

O

NA

cartItem

O

NA

O

NA

relatedParty

O

NA

M

NA

note

O

NA

O

NA

validFor

O

NA

O

NA

contactMedium

O

NA

O

NA

 

 

GET / shoppingCart /{ID} ? ?fields=...&{filtering}

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

-           Any of the mandatory attributes in the first level of shopping cart resource definition

 

API POST OPERATION CONFORMANCE

POST to / shoppingCart

This operation is used to create a Shopping Cart resource in the server.

The response to this operation must include a Location header set to / shoppingCart /{ID} where {ID} indicates the identifier assigned by the server to the new shopping cart 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 shopping cart resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as aprt of the BODY of the POST request message:

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

N

 

 

cartTotalPrice

N

 

 

cartItem

N

 

 

relatedParty

N

 

 

note

N

 

 

validFor

N

 

 

contactMedium

N

 

 

 

The response from the server must 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 BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

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 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 shopping cart API.

Test Cases must be executed in order 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}/ shoppingCart /v1 , being {serverRoot} defines the certification endpoint

Shopping Cart resource TEST CASES

Nominal Scenarios

TC_Cust_N1 – Create new shopping cart (including item) with minimum mandatory information

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

{

 

}

Note: there are no mandatory fields for the creation.

  • 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}/ shoppingCart /{IDcst1} where {IDcst1} indicates the identifier assigned by the server to the new shopping cart resource

 

-           The response message includes all mandatory parameters

 

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

 

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

 

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

 

-           Response Code 200-OK

 

-           The body of the response includes one shopping cart resource with ID set to {IDcst1}, 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 {IDcst1} matches the values set in the original request

 

  • Send a GET message to /{apiRoot}/ shoppingCart /{IDcst1}

 

  • 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 shoppingCart resource structure that matches the values in the original request

 

 

 

TC_ ShoppingCart _N 2 – Search for shopping cart with specific characteristics

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

 

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

-           Response Code 200-OK

 

-           The body of the response includes at least one shopping cart resource

 

-           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}/ shoppingCart /? relatedParty =cst1

 

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

 

-           Response Code 200-OK

 

-           The body of the response includes one shopping cart resource referring to {IDcst1}

 

-           The response message includes all mandatory parameters

 

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