_______________________________________

API Specification Doc

(Web API- Costing Web service)
__________________________________________________________________

COSTING WEB API SPECIFICATION

VERSION 1.3
20/01/2015

Created By: KARTHIKEYAN DANUSKODI

Page 1 of 13
Amendments in this release:
(Including problems cleared and changes applied)

Distribution:

Version Date Issued Issued To Description

1.0 28-Nov-2014 Monisha Craig / Web Initial draft
API Project Team
Members
1.1 16-Dec-2014 Monisha Craig / Web Updates
API Project Team
Members
1.2 13-Jan-2015 Monisha Craig / Web Updates
API Project Team
Members
1.3 20-Jan-2015 Monisha Craig / Web Updates
API Project Team
Members

Page 2 of 13
 Index

Contents
Document Acceptance and Release Notice ................................................... Error! Bookmark not defined.
Amendment History: ..................................................................................... Error! Bookmark not defined.
Amendments in this release: ....................................................................................................................... 2
Costing Web API............................................................................................................................................ 4
1. GetDataSet ............................................................................................................................................ 5
Request ................................................................................................................................................. 5
2. GetCategories ....................................................................................................................................... 6
Request ................................................................................................................................................. 6
3. GetCategoryEntriesWithItems .............................................................................................................. 7
Request ................................................................................................................................................. 7
4. GetItemCostingById .............................................................................................................................. 9
Conventions ............................................................................................................................................ 12
Status Codes............................................................................................................................................ 12

Page 3 of 13
Costing Web API
The purpose of this document is to provide a high level specification for the Cordell “Costing” Web
Service API (Application Programming Interface). We expect the readers of this document will already
have an understanding of basic API/Web Services concepts.

The Costing Web API web service will be used by Cordell clients to get Costing details whenever they
require. Once the API is called by the client, we will validate and authorize the client and return Costing
information based on the level of access they have and information they required. The response will be
in XML format by default.

For initial data population of local databases, clients are expected to make several calls by “dataset ID”
to get all costing data based on the client access. For Costing data updates, several calls may be required
depending on the data requested by clients.

There will be only one web service URL be exposed and that particular web service will have various
methods for clients to decide and call based on the data they require.

The web methods described below are some of the possible scenarios for the API calls and it can be
extended to create as many web methods as required to service the customer needs.

Web Service:

When the client requires data from Cordell, the client will establish a connection to the Costing Web API
by calling the Costing Web API URL link and passing the user credentials. The Costing Web API will check
the credentials and will issue “Access token” in the response as JSON value. These access token will be
then used in the subsequent API method calls from the client. The Access token will have issue time and
Expire time stored in API database. Once the token expired, the client has to provide user credentials
and get a new token. A user can Login from different IP address at the same time and will be issued
different tokens for each login.
Client can use any technology such as Java, PHP and .NET to call and receive data from the web service
as it will use the cross-platform standard SOAP protocol. Sample code for web service method calls will
be provided in the user manual in different programming languages for client to use.

For audit purposes, the Costing Web API will maintain an audit trail table for every request by logging
user details, date & time, IP address, request and their downloaded record count.

The Costing Web API will validate each user call against the user profile/license data based on platform
and Dataset
Page 4 of 13
Whenever client downloads the data, last downloaded date and time for that particular method will be
maintained in the Costing API database, which will be used to give the latest created and modified data
to the client on each call. For example if the client makes the first call on 14th Jan 2015 4PM, We record
this time and send the entire data available at that time. If the client makes next call on 18th June 2015
9AM. System will record that time and respond with the additions and updates made between 14th Jan
2015 4PM and 18th June 2015 9AM. This way whenever the client calls we always give the updates not
the entire data. Client can request full data if required by passing an optional parameter for all the
methods.

Web Methods

1. GetDataSet
This web method will return all the dataset name and id in the costing database. It will not check any
user license details.

An optional input parameter “Complete set” as an integer value of 1 can be passed to the method if the
user wants complete datasets list rather than an updated list. If the optional parameter not passed,
updated data will be provided.

Content Type

application/soap+ xml; charset= utf- 8

Request

Method URL

POST Costing/GetDataset/

INPUT Parameters for the request XML

Parameters Values
COMPLETESET INTEGER < COMPLETESET > INTEGER </ COMPLETESET >

Page 5 of 13
Output Parameters for the response XML
Parameters Values
DATASETID INTEGER < DATASETID > INTEGER </ DATASETID >
NAME STRING < NAME > STRING </ NAME >
DATASETSTATUS STRING < DATASETSTATUS > STRING </ DATASETSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >

2. GetCategories
This web method will return the categories name and id in the costing database. It will not check any
user license details.

An optional input parameter “Complete set” as an integer value of 1 can be passed to the method if the
user wants complete Category list rather than an updated list. If the optional parameter not passed,
updated data will be provided.

Content Type

application/soap+ xml; charset= utf- 8

Request

Method URL

POST Costing/GetCategories/

INPUT Parameters for the request XML

Parameters Values
COMPLETESET INTEGER < COMPLETESET > INTEGER </ COMPLETESET >

Output Parameters for the response XML

Parameters Values
CATEGORYID INTEGER < CATEGORYID > INTEGER </ CATEGORYID >
Page 6 of 13
CODE STRING < CODE > STRING </ CODE >
DESCRIPTION STRING < DESCRIPTION > STRING </ DESCRIPTION >
LINENO STRING < LINENO > STRING </ LINENO >
CATEGORYSTATUS STRING < CATEGORYSTATUS > STRING </ CATEGORYSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >
TIPID INTEGER < TIPID > INTEGER </ TIPID >
TIPDESCRIPTION STRING < TIPDESCRIPTION > STRING </ TIPDESCRIPTION >
TIPDATECREATED STRING < TIPDATECREATED > STRING </ TIPDATECREATED >
TIPDATEMODIFIED STRING < TIPDATEMODIFIED > STRING </ TIPDATEMODIFIED >
TIPDATEDELETED STRING < TIPDATEDELETED > STRING </ TIPDATEDELETED >

3. GetCategoryEntriesWithItems
This web method will be used to get the list of available Entries, Items, Ingredients in costing database
based on the dataset id passed by the client. This method will validate whether client has access to
dataset they have requested for. If they don’t have access to dataset they requested for we will return a
message to contact Cordell representative.

The ingredients in costing database will be given only to the privileged users with proper access rights;
regular users will get only the entries and Items with this method. A single xml file with Entry, Items and
Ingredients nodes will be created in the response.

An optional input parameter “Complete set” as an integer value of 1 can be passed to the method if the
user wants complete Entry and items list rather than an updated list. If the optional parameter not
passed, updated data will be provided.

Content Type

application/soap+ xml; charset= utf- 8

Request

Method URL

Page 7 of 13
POST Costing/GetCategoryEntriesWithItems/

Input parameters
Parameters Values
DATASET STRING < DATASET >STRING</ DATASET >
COMPLETESET INTEGER < COMPLETESET > INTEGER </ COMPLETESET >

Output Parameters for the Entry response XML

Parameters Values
ENTRYID INTEGER < ENTRYID > INTEGER </ ENTRYID >
CATEGORYID INTEGER < CATEGORYID > INTEGER </ CATEGORYID >
TYPE STRING < TYPE > STRING </ TYPE >
CODE STRING < CODE > STRING </ CODE >
DESCRIPTION STRING < DESCRIPTION > STRING </ DESCRIPTION >
RECIPETYPEID STRING < RECIPETYPEID > STRING </ RECIPETYPEID >
COMPONENTTYPE STRING < COMPONENTTYPE > STRING </ COMPONENTTYPE >
ENTRYSTATUS STRING < ENTRYSTATUS > STRING </ ENTRYSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >

Output Parameters for the Items response XML

Parameters Values
ITEMID INTEGER < ITEMID > INTEGER </ ITEMID >
ENTRYID INTEGER < ENTRYID > INTEGER </ ENTRYID >
CATEGORYID INTEGER < CATEGORYID > INTEGER </ CATEGORYID >
ITEMCODE STRING < ITEMCODE > STRING </ ITEMCODE >
DESCRIPTION STRING < DESCRIPTION > STRING </ DESCRIPTION >
WORKAREA STRING < WORKAREA > STRING </ WORKAREA >
UNITMEASURE STRING < UNITMEASURE > STRING </ UNITMEASURE >
ITEMSTATUS STRING < ITEMSTATUS > STRING </ ITEMSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >

Page 8 of 13
Output Parameters for the Ingredients response XML
Parameters Values
ID INTEGER < ID > INTEGER </ ID >
ITEMID INTEGER < ITEMID > INTEGER </ ITEMID >
QUANTITY STRING < QUANTITY > STRING </ QUANTITY >
ENTRYID INTEGER < ENTRYID > INTEGER </ ENTRYID >
CATEGORYID INTEGER < CATEGORYID > INTEGER </ CATEGORYID >
INGREDIENTID INTEGER < INGREDIENTID > INTEGER </ INGREDIENTID >
< INGREDIENTITEMCODE > STRING </
INGREDIENTITEMCODE STRING INGREDIENTITEMCODE >
DESCRIPTION STRING < DESCRIPTION > STRING </ DESCRIPTION >
UNITMEASURE STRING < UNITMEASURE > STRING </ UNITMEASURE >
INGREDIENTSTATUS STRING < INGREDIENTSTATUS > STRING </ INGREDIENTSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >

4. GetItemCostingById
This web method will be used to get the individual item costing data by passing item code, dataset and
region. This method will validate whether client has access dataset they have requested for. If not
system will respond with the message saying to contact Cordell representative.

Content Type

application/soap+ xml; charset= utf- 8

Request

Method URL

POST Projects/GetItemCostingById/

Page 9 of 13
Input Parameters

Type Parameters Values

POST ITEMCODE STRING < ITEMCODE > STRING </ ITEMCODE >
POST DATASETID INTEGER < DATASETID > INTEGER </ DATASETID >
POST REGIONID INTEGER < REGIONID > INTEGER </ REGIONID >

Output Parameters for the response XML – Normal users

Parameters Values
PRICESUMMARYID INTEGER < PRICESUMMARYID > INTEGER </ PRICESUMMARYID >
ITEMID INTEGER < ITEMID > INTEGER </ ITEMID >
DATASETID INTEGER < DATASETID > INTEGER </ DATASETID >
ITEMCODE STRING < ITEMCODE > STRING </ ITEMCODE >
LABOUR STRING < LABOUR > STRING </ LABOUR >
MATERIAL STRING < MATERIAL > STRING </ MATERIAL >
PLANT STRING < PLANT > STRING </ PLANT >
SUBCONTRACT STRING < SUBCONTRACT > STRING </ SUBCONTRACT >
TOTALBAPRICE STRING < TOTALBAPRICE > STRING </ TOTALBAPRICE >
< ADJUSTMENTPERCENTAGE > STRING </
ADJUSTMENTPERCENTAGE STRING ADJUSTMENTPERCENTAGE >
PUBLISHEDPRICE STRING < PUBLISHEDPRICE > STRING </ PUBLISHEDPRICE >
REGIONID INTEGER < REGIONID > INTEGER </ REGIONID >
PRICESECTORID INTEGER < PRICESECTORID > INTEGER </ PRICESECTORID >
< PRICESUMMARYSTATUS > STRING </
PRICESUMMARYSTATUS STRING PRICESUMMARYSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >

Output Parameters for the response XML – Privileged users

Parameters Values
PRICESUMMARYID INTEGER < PRICESUMMARYID > INTEGER </ PRICESUMMARYID >
Page 10 of 13
ITEMID INTEGER < ITEMID > INTEGER </ ITEMID >
DATASETID INTEGER < DATASETID > INTEGER </ DATASETID >
ITEMCODE STRING < ITEMCODE > STRING </ ITEMCODE >
LABOUR STRING < LABOUR > STRING </ LABOUR >
MATERIAL STRING < MATERIAL > STRING </ MATERIAL >
PLANT STRING < PLANT > STRING </ PLANT >
SUBCONTRACT STRING < SUBCONTRACT > STRING </ SUBCONTRACT >
TOTALBAPRICE STRING < TOTALBAPRICE > STRING </ TOTALBAPRICE >
< ADJUSTMENTPERCENTAGE > STRING </
ADJUSTMENTPERCENTAGE STRING ADJUSTMENTPERCENTAGE >
PUBLISHEDPRICE STRING < PUBLISHEDPRICE > STRING </ PUBLISHEDPRICE >
REGIONID INTEGER < REGIONID > INTEGER </ REGIONID >
PRICESECTORID INTEGER < PRICESECTORID > INTEGER </ PRICESECTORID >
< PRICESUMMARYSTATUS > STRING </
PRICESUMMARYSTATUS STRING PRICESUMMARYSTATUS >
DATECREATED STRING < DATECREATED > STRING </ DATECREATED >
DATEMODIFIED STRING < DATEMODIFIED > STRING </ DATEMODIFIED >
DATEDELETED STRING < DATEDELETED > STRING </ DATEDELETED >
INGREDIENTPRICESUMMARY < INGREDIENTPRICESUMMARYID > INTEGER </
ID INTEGER INGREDIENTPRICESUMMARYID >
INGREDIENTITEMID INTEGER < INGREDIENTITEMID > INTEGER </ INGREDIENTITEMID >
<INGREDIENT DATASETID > INTEGER
INGREDIENTDATASETID INTEGER </INGREDIENTDATASETID >
< INGREDIENTITEMCODE > STRING </
INGREDIENTITEMCODE STRING INGREDIENTITEMCODE >
INGREDIENTLABOUR STRING < INGREDIENTLABOUR > STRING </INGREDIENTLABOUR >
< INGREDIENTMATERIAL > STRING
INGREDIENTMATERIAL STRING </INGREDIENTMATERIAL >
INGREDIENTPLANT STRING <INGREDIENT PLANT > STRING </INGREDIENTPLANT >
< INGREDIENTSUBCONTRACT > STRING </
INGREDIENTSUBCONTRACT STRING INGREDIENTSUBCONTRACT >
< INGREDIENTTOTALBAPRICE > STRING </
INGREDIENTTOTALBAPRICE STRING INGREDIENTTOTALBAPRICE >
INGREDIENTADJUSTMENTPE < INGREDIENTADJUSTMENTPERCENTAGE > STRING </
RCENTAGE STRING INGREDIENTADJUSTMENTPERCENTAGE >
INGREDIENTPUBLISHEDPRIC <INGREDIENT PUBLISHEDPRICE > STRING </
E STRING INGREDIENTPUBLISHEDPRICE >
INGREDIENTREGIONID INTEGER < INGREDIENTREGIONID > INTEGER </ REGIONID >
< INGREDIENTPRICESECTORID > INTEGER </
INGREDIENTPRICESECTORID INTEGER INGREDIENTPRICESECTORID >

Page 11 of 13
Glossary
Conventions
● Client - Client application.
● Status - HTTP status code of response.
● All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued
per request server.
● All response is in XML format.
● All request parameters are optional unless explicitly marked as [mandatory]

Status Codes
All status codes are standard HTTP status codes. The below ones are used in this API.

2XX - Success of some kind

4XX - Error occurred in client’s part
5XX - Error occurred in server’s part

Status Code Description

200 OK

201 Created

202 Accepted (Request accepted, and queued for execution)

400 Bad request

401 Authentication failure

403 Forbidden

404 Resource not found

405 Method Not Allowed

Page 12 of 13
409 Conflict

412 Precondition Failed

413 Request Entity Too Large

500 Internal Server Error

501 Not Implemented

503 Service Unavailable

Details Required:

1. Require complete data fields passed back to client for all methods –Schema details given to
Umesh for verification –Umesh confirmed the schema.
2. How regions and sector details are shared with customers? -
3. Whether the freeform, heading categories and groups will be exposed to customers? Yes
4. Only marked “Group Publications” items need to be exposed to client? – When Parent item
is marked for publication, child items will be exposed even if they are not marked for
publications.
5. When only privileged users can access the ingredients details, is it necessary to expose
component items to the normal users? – Yes .Even normal users will get the price details of
the component items.

Page 13 of 13