Webservice API Specification Doc Template.docx



_______________________________________API Specification Doc(Web API- Costing Web service)__________________________________________________________________Costing WEB API SPECIFICATIONVERSION 1.320/01/2015Created By: KARTHIKEYAN DANUSKODIAmendments in this release:(Including problems cleared and changes applied)Distribution: VersionDate IssuedIssued ToDescription1.028-Nov-2014Monisha Craig / Web API Project Team MembersInitial draft1.116-Dec-2014Monisha Craig / Web API Project Team MembersUpdates1.213-Jan-2015Monisha Craig / Web API Project Team MembersUpdates1.320-Jan-2015Monisha Craig / Web API Project Team MembersUpdatesIndexContents TOC \o "1-3" \h \z \u Document Acceptance and Release Notice PAGEREF _Toc406495045 \h 2Amendment History: PAGEREF _Toc406495046 \h 2Amendments in this release: PAGEREF _Toc406495047 \h 3Costing Web API PAGEREF _Toc406495048 \h 51.GetDataSet PAGEREF _Toc406495049 \h 6Request PAGEREF _Toc406495050 \h 62.GetCategories PAGEREF _Toc406495051 \h 6Request PAGEREF _Toc406495052 \h 73.GetCategoryEntriesWithItems PAGEREF _Toc406495053 \h 8Request PAGEREF _Toc406495054 \h 84. GetItemCostingById PAGEREF _Toc406495055 \h 9Conventions PAGEREF _Toc406495056 \h 11Status Codes PAGEREF _Toc406495057 \h 11Costing 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 DatasetWhenever 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 MethodsGetDataSetThis 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 Typeapplication/soap+ xml; charset= utf- 8RequestMethodURL POSTCosting/GetDataset/INPUT Parameters for the request XMLParametersValues?COMPLETESETINTEGER< COMPLETESET > INTEGER </ COMPLETESET >Output Parameters for the response XMLParametersValues?DATASETIDINTEGER< DATASETID > INTEGER </ DATASETID >NAMESTRING< NAME > STRING </ NAME >DATASETSTATUSSTRING< DATASETSTATUS > STRING </ DATASETSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >GetCategoriesThis 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 Typeapplication/soap+ xml; charset= utf- 8RequestMethodURL POSTCosting/GetCategories/INPUT Parameters for the request XMLParametersValues?COMPLETESETINTEGER< COMPLETESET > INTEGER </ COMPLETESET >Output Parameters for the response XMLParametersValues?CATEGORYIDINTEGER< CATEGORYID > INTEGER </ CATEGORYID >CODESTRING< CODE > STRING </ CODE >DESCRIPTIONSTRING< DESCRIPTION > STRING </ DESCRIPTION >LINENOSTRING< LINENO > STRING </ LINENO >CATEGORYSTATUSSTRING< CATEGORYSTATUS > STRING </ CATEGORYSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >TIPIDINTEGER< TIPID > INTEGER </ TIPID >TIPDESCRIPTIONSTRING< TIPDESCRIPTION > STRING </ TIPDESCRIPTION >TIPDATECREATEDSTRING< TIPDATECREATED > STRING </ TIPDATECREATED >TIPDATEMODIFIEDSTRING< TIPDATEMODIFIED > STRING </ TIPDATEMODIFIED >TIPDATEDELETEDSTRING< TIPDATEDELETED > STRING </ TIPDATEDELETED >GetCategoryEntriesWithItemsThis 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 Typeapplication/soap+ xml; charset= utf- 8RequestMethodURL POSTCosting/GetCategoryEntriesWithItems/Input parametersParametersValues?DATASETSTRING< DATASET >STRING</ DATASET >COMPLETESETINTEGER< COMPLETESET > INTEGER </ COMPLETESET >Output Parameters for the Entry response XMLParametersValues?ENTRYIDINTEGER< ENTRYID > INTEGER </ ENTRYID >CATEGORYIDINTEGER< CATEGORYID > INTEGER </ CATEGORYID >TYPESTRING< TYPE > STRING </ TYPE >CODESTRING< CODE > STRING </ CODE >DESCRIPTIONSTRING< DESCRIPTION > STRING </ DESCRIPTION >RECIPETYPEIDSTRING< RECIPETYPEID > STRING </ RECIPETYPEID >COMPONENTTYPESTRING< COMPONENTTYPE > STRING </ COMPONENTTYPE >ENTRYSTATUSSTRING< ENTRYSTATUS > STRING </ ENTRYSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >Output Parameters for the Items response XMLParametersValues?ITEMIDINTEGER< ITEMID > INTEGER </ ITEMID >ENTRYIDINTEGER< ENTRYID > INTEGER </ ENTRYID >CATEGORYIDINTEGER< CATEGORYID > INTEGER </ CATEGORYID >ITEMCODESTRING< ITEMCODE > STRING </ ITEMCODE >DESCRIPTIONSTRING< DESCRIPTION > STRING </ DESCRIPTION >WORKAREASTRING< WORKAREA > STRING </ WORKAREA >UNITMEASURESTRING< UNITMEASURE > STRING </ UNITMEASURE >ITEMSTATUSSTRING< ITEMSTATUS > STRING </ ITEMSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >Output Parameters for the Ingredients response XMLParametersValues?IDINTEGER< ID > INTEGER </ ID >ITEMIDINTEGER< ITEMID > INTEGER </ ITEMID >QUANTITYSTRING< QUANTITY > STRING </ QUANTITY >ENTRYIDINTEGER< ENTRYID > INTEGER </ ENTRYID >CATEGORYIDINTEGER< CATEGORYID > INTEGER </ CATEGORYID >INGREDIENTIDINTEGER< INGREDIENTID > INTEGER </ INGREDIENTID >INGREDIENTITEMCODESTRING< INGREDIENTITEMCODE > STRING </ INGREDIENTITEMCODE >DESCRIPTIONSTRING< DESCRIPTION > STRING </ DESCRIPTION >UNITMEASURESTRING< UNITMEASURE > STRING </ UNITMEASURE >INGREDIENTSTATUSSTRING< INGREDIENTSTATUS > STRING </ INGREDIENTSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >4. GetItemCostingByIdThis 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 Typeapplication/soap+ xml; charset= utf- 8RequestMethodURL POSTProjects/GetItemCostingById/Input ParametersTypeParametersValues?POSTITEMCODESTRING< ITEMCODE > STRING </ ITEMCODE >POSTDATASETIDINTEGER< DATASETID > INTEGER </ DATASETID >POSTREGIONIDINTEGER< REGIONID > INTEGER </ REGIONID >Output Parameters for the response XML – Normal usersParametersValues?PRICESUMMARYIDINTEGER< PRICESUMMARYID > INTEGER </ PRICESUMMARYID >ITEMIDINTEGER< ITEMID > INTEGER </ ITEMID >DATASETIDINTEGER< DATASETID > INTEGER </ DATASETID >ITEMCODESTRING< ITEMCODE > STRING </ ITEMCODE >LABOURSTRING< LABOUR > STRING </ LABOUR >MATERIALSTRING< MATERIAL > STRING </ MATERIAL >PLANTSTRING< PLANT > STRING </ PLANT >SUBCONTRACTSTRING< SUBCONTRACT > STRING </ SUBCONTRACT >TOTALBAPRICESTRING< TOTALBAPRICE > STRING </ TOTALBAPRICE >ADJUSTMENTPERCENTAGESTRING< ADJUSTMENTPERCENTAGE > STRING </ ADJUSTMENTPERCENTAGE >PUBLISHEDPRICESTRING< PUBLISHEDPRICE > STRING </ PUBLISHEDPRICE >REGIONIDINTEGER< REGIONID > INTEGER </ REGIONID >PRICESECTORIDINTEGER< PRICESECTORID > INTEGER </ PRICESECTORID >PRICESUMMARYSTATUSSTRING< PRICESUMMARYSTATUS > STRING </ PRICESUMMARYSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >Output Parameters for the response XML – Privileged users ParametersValues?PRICESUMMARYIDINTEGER< PRICESUMMARYID > INTEGER </ PRICESUMMARYID >ITEMIDINTEGER< ITEMID > INTEGER </ ITEMID >DATASETIDINTEGER< DATASETID > INTEGER </ DATASETID >ITEMCODESTRING< ITEMCODE > STRING </ ITEMCODE >LABOURSTRING< LABOUR > STRING </ LABOUR >MATERIALSTRING< MATERIAL > STRING </ MATERIAL >PLANTSTRING< PLANT > STRING </ PLANT >SUBCONTRACTSTRING< SUBCONTRACT > STRING </ SUBCONTRACT >TOTALBAPRICESTRING< TOTALBAPRICE > STRING </ TOTALBAPRICE >ADJUSTMENTPERCENTAGESTRING< ADJUSTMENTPERCENTAGE > STRING </ ADJUSTMENTPERCENTAGE >PUBLISHEDPRICESTRING< PUBLISHEDPRICE > STRING </ PUBLISHEDPRICE >REGIONIDINTEGER< REGIONID > INTEGER </ REGIONID >PRICESECTORIDINTEGER< PRICESECTORID > INTEGER </ PRICESECTORID >PRICESUMMARYSTATUSSTRING< PRICESUMMARYSTATUS > STRING </ PRICESUMMARYSTATUS >DATECREATEDSTRING< DATECREATED > STRING </ DATECREATED >DATEMODIFIEDSTRING< DATEMODIFIED > STRING </ DATEMODIFIED >DATEDELETEDSTRING< DATEDELETED > STRING </ DATEDELETED >INGREDIENTPRICESUMMARYIDINTEGER< INGREDIENTPRICESUMMARYID > INTEGER </ INGREDIENTPRICESUMMARYID >INGREDIENTITEMIDINTEGER< INGREDIENTITEMID > INTEGER </ INGREDIENTITEMID >INGREDIENTDATASETIDINTEGER<INGREDIENT DATASETID > INTEGER </INGREDIENTDATASETID >INGREDIENTITEMCODESTRING< INGREDIENTITEMCODE > STRING </ INGREDIENTITEMCODE >INGREDIENTLABOURSTRING< INGREDIENTLABOUR > STRING </INGREDIENTLABOUR >INGREDIENTMATERIALSTRING< INGREDIENTMATERIAL > STRING </INGREDIENTMATERIAL >INGREDIENTPLANTSTRING<INGREDIENT PLANT > STRING </INGREDIENTPLANT >INGREDIENTSUBCONTRACTSTRING< INGREDIENTSUBCONTRACT > STRING </ INGREDIENTSUBCONTRACT >INGREDIENTTOTALBAPRICESTRING< INGREDIENTTOTALBAPRICE > STRING </ INGREDIENTTOTALBAPRICE >INGREDIENTADJUSTMENTPERCENTAGESTRING< INGREDIENTADJUSTMENTPERCENTAGE > STRING </ INGREDIENTADJUSTMENTPERCENTAGE >INGREDIENTPUBLISHEDPRICESTRING<INGREDIENT PUBLISHEDPRICE > STRING </ INGREDIENTPUBLISHEDPRICE >INGREDIENTREGIONIDINTEGER< INGREDIENTREGIONID > INTEGER </ REGIONID >INGREDIENTPRICESECTORIDINTEGER< INGREDIENTPRICESECTORID > INTEGER </ INGREDIENTPRICESECTORID >GlossaryConventionsClient - 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 CodesAll status codes are standard HTTP status codes. The below ones are used in this API.2XX - Success of some kind4XX - Error occurred in client’s part5XX - Error occurred in server’s partStatus CodeDescription200OK201Created202Accepted (Request accepted, and queued for execution)400Bad request401Authentication failure403Forbidden404Resource not found405Method Not Allowed409Conflict412Precondition Failed413Request Entity Too Large500Internal Server Error501Not Implemented503Service UnavailableDetails Required:Require complete data fields passed back to client for all methods –Schema details given to Umesh for verification –Umesh confirmed the schema.How regions and sector details are shared with customers? -Whether the freeform, heading categories and groups will be exposed to customers? YesOnly 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.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. ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download