API Reference Document - .NET Framework



GLIMR APIDocumentation Version 1.0 ● DATE \@ "dd MMMM yyyy" 21 February 2018MICROSOFTTrademarksDisclaimerThe information provided in this document is provided "as is" without warranty of any kind. Launch Consulting disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a purpose. In no event, shall Microsoft be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if Launch Consulting or its suppliers have been advised of the possibility of such damages.Document LifetimeMicrosoft may occasionally update online documentation between releases of the related software. Consequently, if this document was not downloaded recently, it may not contain the most up-to-date information. Please contact Glimr support team for the most current information.Where to get help?Technical support — Contact GLIMR Support.Your comments?Your suggestions will help us continue to improve the accuracy, organization, and overall quality of the user publications. Please send your opinion of this document to:? HYPERLINK "mailto:glimrsup@" glimrsup@If you have issues, comments, or questions about specific information or procedures, please include the title and, if available, the part number, the revision, the page numbers, and any other details that will help us locate the subject that you are addressing.PrefaceIntended AudienceThis guide is part of the GLIMR documentation set. It is intended for use by API User. Readers should be familiar with the following GLIMR Application ()Table of Contents TOC \o "1-2" \h \z \u 1.Overview PAGEREF _Toc507087626 \h 61.1.Conventions PAGEREF _Toc507087627 \h 61.2.Current Version PAGEREF _Toc507087628 \h 61.3.Schema PAGEREF _Toc507087629 \h 61.4.HTTP Redirects PAGEREF _Toc507087630 \h 71.5.HTTP Requests PAGEREF _Toc507087631 \h 71.6.HTTP Methods PAGEREF _Toc507087632 \h 71.7.Authentication PAGEREF _Toc507087633 \h 81.8.Pagination PAGEREF _Toc507087634 \h 91.9.Rate Limiting PAGEREF _Toc507087635 \h 91.10.URL Format PAGEREF _Toc507087636 \h 92.API Reference Documentation PAGEREF _Toc507087637 \h 112.1.Overview PAGEREF _Toc507087638 \h 113.RequestStatusReport PAGEREF _Toc507087639 \h 133.1.Resource Information PAGEREF _Toc507087640 \h 133.2.Request PAGEREF _Toc507087641 \h 133.1.Parameters PAGEREF _Toc507087642 \h 133.2.Authorization PAGEREF _Toc507087643 \h 133.3.Response PAGEREF _Toc507087644 \h 143.1.Samples PAGEREF _Toc507087645 \h 154.SupplierAssetsCheckIn PAGEREF _Toc507087646 \h 204.1.Resource Information PAGEREF _Toc507087647 \h 204.2.Request PAGEREF _Toc507087648 \h 204.3.Parameters PAGEREF _Toc507087649 \h 204.4.Authorization PAGEREF _Toc507087650 \h 214.5.Response PAGEREF _Toc507087651 \h 214.6.Samples - CheckoutRequest PAGEREF _Toc507087652 \h 215.AssetStatusReport PAGEREF _Toc507087653 \h 235.1.Resource Information PAGEREF _Toc507087654 \h 235.2.Request PAGEREF _Toc507087655 \h 235.3.Parameters PAGEREF _Toc507087656 \h 235.4.Authorization PAGEREF _Toc507087657 \h 235.5.Response PAGEREF _Toc507087658 \h 245.6.Samples - PAGEREF _Toc507087659 \h 256.Query Parameters PAGEREF _Toc507087660 \h 277.Status Codes PAGEREF _Toc507087661 \h 288.Additional Sample Request/Response SupplierAssetsCheckIn (AssetNotFound) PAGEREF _Toc507087662 \h 299.InStockAssetsCheckIn PAGEREF _Toc507087663 \h 3510.CheckOut Request PAGEREF _Toc507087664 \h 3711.Close Request PAGEREF _Toc507087665 \h 40Document HistoryPaper copies are valid only on the day they are printed. Contact the GLIMR Support if you are in any doubt about the accuracy of this document.Revision HistoryThis document has been revised by:Revision NumberRevision DateSummary of ChangesAuthorv14-21-2017Initial Document ReleaseGlimr Teamv22/20/2018Added more functionalityGlimr Teamv3Reference Documents None.Distribution ListNone.OverviewThe GLIMR Application has created a web API at . This feature has been created for 3rd party vendors to have external access. Vendors will use the web API to obtain request information and obtain asset details. Thus, allowing the vendors to process requests and manage inventory in compliance with Microsoft rules and regulations.ConventionsWe use the following conventions in this document:Responses are listed under ‘Responses’ for each method. Responses are in JSON format.Request parameters are mandatory unless explicitly marked as Optional.The type of values accepted for a request parameter are shown the values column.The | symbol means OR. Current VersionBy default, all requests receive the v1 version of the API. SchemaAll API access is over HTTPS, and accessed from the data is sent and received as JSON.All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZSummary Representations - When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the "summary" representation of the resource.Detailed Representations - When you fetch an individual resource, the response typically includes all attributes for that resource. This is the "detailed" representation of the resource.HTTP RedirectsStatus CodeDescription301Permanent redirection. The URL used to make the request has been superseded by the one specified in the Location header field. Direct this and all future requests to this resource to the new URL.302, 307Temporary redirection. The request should be repeated verbatim to the URL specified in the Location header field, but clients should continue to use the original URL for future requests.HTTP RequestsHTTP Method: Describes the type of HTTP action (POST, GET, PUT or DELETE)URL: Describes the resource you are creating or accessing, along with any optional argumentsHTTP Headers: Specifies attributes of the request, including authentication, encoding and request formatRequest Body: Describes resources or specifies a call-control scriptHTTP MethodsIdentify the methods used in this document.The GLIMR API supports POST, GET methods.POSTUpdates an existing resource.Example: POST /token Updates an existing photo.GETRetrieves an existing resource.Example: GET / api/RequestStatusReportRetrieves all request for a given request status.PUTExample: /api/CloseRequestAuthenticationHere are the steps for authentication:The client application sends a request to Authentication server endpoint with a credential.If the username and password are found correct, then the Authentication server sends a token to the client as a response. Token contains data to identify a user and an expiry time.Client application then uses the token to access the method/resources in next requests while the token is validSample Token Request using Postman:Download postman as a part of Google chrome browser extension.Requesting Token using PostmanRequesting resource with TokenPaginationNoneRate LimitingNoneURL FormatThe API URL uses the following format: <protocol>://<host>:<port>/api/<MethodName>Example: GET Reference DocumentationHere are the details of GLIMR API resources, their parameters, and code samples. OverviewList of methods for GLIMRAPI Note that the term method and resource (and object) tend to be used interchangeable in API documentation. MethodPurposeRequestStatusReportThis API call returns all request with requested asset details for a given statusAssetStatusReportThis API call returns all assets from specified sub/groupCloseRequestThis API call will close the associated request.CheckoutRequestThis API will checkout the associated requestInstockAssetsCheckinChecks in GLIMR assets by AssetId or Asset-TagSupplierAssetsCheckInChecks in Supplier assets by AssetId and AssetType (Device, Accessory, AssetNotFound)RequestStatusReportResource InformationMethodPurposeResponse formatsJSONRequires authentication?YesRate limited?NoRequests-Request HTTP method and the URL for API: MethodURLGET This API includes the following optional and required parameters:NameTypeDescriptionRequiredsubsidiarystringSubsidiary NameYesrequeststatusstringRequest StatusYesgroupstringGroup NameNoAuthorization This method takes Bearer token as a parameter to validate the request, and the token is valid for one day.Response If method call successful, this method returns a response body with the following structure:[ { "RequestId": 2099, "RequestStatusName": "Checkout", "RequestNeedByDate": "2017-10-31T07:00:00", "RequestType": "Giveaway", "GroupName": "TestGroup01", "LocationName": null, "Comments": null, "AgreementSent": "0001-01-01T00:00:00", "AgreementSigned": "0001-01-01T00:00:00", "AssetDetail": [ { "AssetId": 0, "AssetType": null, "ManufacturerName": "Microsoft", "FormFactor": "Laptop|Tablet", "Model": "Surface 3", "Configuration": "null, 4GB, 64GB, 10.8\", null", "AssetIdentifier": null, "QuatityApproved": 0, "ApproverAlias": "", "ReservedByAlias": null, "QuantityReserved": 0, "AssetGroup": "TestGroup01", "AssetLocation": null, "IsSupplierAsset": "N", "SupplierName": "N/A" }, { "AssetId": 0, "AssetType": null, "ManufacturerName": "Microsoft", "FormFactor": "Game Console", "Model": "Xbox One S", "Configuration": "2TB", "AssetIdentifier": "", "QuatityApproved": 1, "ApproverAlias": "v-brocka", "ReservedByAlias": null, "QuantityReserved": 0, "AssetGroup": "TestGroup01", "AssetLocation": null, "IsSupplierAsset": "N", "SupplierName": "N/A" }]NameTypeDescriptionRequestIdintegerAn ID that identifies this Request.RequestStatusIdintegerAn ID that identifies the request status.RequestStatusNamestringA description of the request status.RequestNeedByDatedatetimeDate that requester expects assets.RequestTypestringType of Request (“Loan” or “Giveaway”).GroupNamestringName of Group fulfilling requested assets.LocationNamestringName of Location fulfilling requested mentsstringAdditional comments from Requester.AgreementSentdatetimeDate/Time agreement sentAgreementSigneddatetimeDate/Time agreement signedAssetDetailJsonObjectContains details about each asset in RequestSamplesThis section provides samples requests and responses. Sample RequestGET ResponseIf successful, returns the HTTP status of 200 and a transaction object. [ { "AssetId": 242654, "AssetTag": null, "SerialNumber": null, "AssetType": "Others", "LoanOrGiveaway": "Giveaway", "ManufacturerName": "XBOX Samples", "FormFactor": null, "ModelName": "Call of duty ghosts (FR)", "Configuration": null, "Quantity": 1, "AssetUID": null, "GroupName": "TestGroup01", "LocationName": "TestLocation01", "IsAvailable": "Yes", "Status": "Active", "Notes": null }]You can also use the following table to document the response.StatusResponse200 [ { "AssetId": 242654, "AssetTag": null, "SerialNumber": null, "AssetType": "Others", "LoanOrGiveaway": "Giveaway", "ManufacturerName": "XBOX Samples", "FormFactor": null, "ModelName": "Call of duty ghosts (FR)", "Configuration": null, "Quantity": 1, "AssetUID": null, "GroupName": "TestGroup01", "LocationName": "TestLocation01", "IsAvailable": "Yes", "Status": "Active", "Notes": null }]403{"error":"API key is missing."}400{"error":"Please provide username."}400{"error":"Please provide password."}401{"error":"Invalid API key."}401{"error":"Incorrect username or password."}500{"error”: “Something went wrong. Please try again."}Using sample C# code to get token/Resource data:Add Restsharp reference using Nuget package managerstatic string GetToken (string url, string userName, string password) { RestClient client = new RestClient(); client.BaseUrl = new Uri(url); var request = new RestRequest(Method.POST); string encodedBody = string.Format("grant_type=password&UserName={0}&Password={1}", userName, password); request.AddParameter("application/x-www-form-urlencoded", encodedBody, ParameterType.RequestBody); var response = client.Execute(request); return response.Content; }static object RequestStatusReport () { string url = "" string token = "Bearer PjxeYZdbCf_eqeSfW8fuDgPA0dARrGINRJ0C3USP80WT2sGYEtd4Kt6wiUyxhba1z"; RestClient client = new RestClient(); client.BaseUrl = new Uri(url); var request = new RestRequest(Method.GET); request.AddParameter("Content-Type", "application/x-www-form-urlencoded", ParameterType.HttpHeader); request.AddParameter("Authorization", token, ParameterType.HttpHeader); var response = client.Execute(request); return response.Content; }SupplierAssetsCheckInIdentify the resource (aka method) and describe its purpose.Resource InformationThe resource information is as follows: MethodPurposeResponse formatsJSONRequires authentication?YesRate limited?NoRequests-Request The HTTP method and URL is as follows: MethodURLGET This API includes the following optional and required parameters:requestId : 38529 assetsToCheckIn : [ { "AssetId": 220, "AssetType": "AssetNotFound", "CheckInQuanity": 2 }]NameTypeDescriptionRequiredrequestIdstringSubsidiary NameYesassetsToCheckInModelObject (AssetId, AssetType, Checkinquantity)YesAuthorization If this request requires authorization, identify the following scopes Response Describe the response body and the structure. For example { "IsSuccess": true}NameTypeDescriptionRequestIdintegerAn ID that identifies this Request.AssetIdsArrayAn ID that identifies the asset ids.AssetTagsArrayAsset Tag.Samples - CheckoutRequestProvide samples requests and responses. Sample RequestGET ResponseIf successful, returns the HTTP status of 200 and a transaction object.{ "IsSuccess": false, "ErrorMessage": "Invalid RequestID."}You can also use the following table to document the response.StatusResponse200{ "IsSuccess": true}403{"error":"API key is missing."}400{"error":"Please provide username."}400{"error":"Please provide password."}401{"error":"Invalid API key."}401{"error":"Incorrect username or password."}500{"error":"Something went wrong. Please try again."}AssetStatusReportIdentify the resource (aka method) and describe its purpose.Resource InformationThe resource information is as follows: MethodPurposeResponse formatsJSONRequires authentication?YesRate limited?NoRequests-Request The HTTP method and URL is as follows: MethodURLGET This API includes the following optional and required parameters:NameTypeDescriptionRequiredsubsidiarystringSubsidiary NameYesavailablestringYes/No FlagYesassetStatusstringAsset StatusYesgroupstringGroup NameYesAuthorization If this request requires authorization, identify the following scopes Response If method call successful, this method returns a response body with the following structure:{ "AssetId": int, "AssetTag": string, "SerialNumber": string, "AssetType": string, "LoanOrGiveaway": string, "ManufacturerName": string, "FormFactor": string, "ModelName": string, "Configuration": string, "Quantity": int, "AssetUID": string, "GroupName": string, "LocationName": string, "IsAvailable": string, "Status": string, "Notes": stringNameTypeDescriptionAssetIdIntAn ID that identifies this Asset.AssetTagstringA unique string that identifies this Asset to the organiztion.SerialNumberstringA unique string that identifies this Asset to the manufacturer.AssetTypestringA description of the Asset type (device, accessory, other).LoanOrGiveawaystringType of Asset (“Loan” or “Giveaway”).ManufacturerNamestringName of manufacturer.FormFactorstringForm factor of asset (laptop, tablet, etc.).ModelNamestringName of Model.ConfigurationstringName of configuration.QuantityintCurrent quantity of particular assetAssetUIDstringUnique identifier of asset (eg., “belongs to Merch group”)GroupNamestringName of Group containing requested assets.LocationNamestringName of Location containing requested assets.IsAvailablestringIs Asset available (yes,no)?StatusstringDescription of Asset statusNotesstring Addition notes about AssetSamples - Provide samples requests and responses. Sample RequestGET ResponseIf successful, returns the HTTP status of 200 and a transaction object.You can also use the following table to document the response.StatusResponse200 "AssetId": 43750, "AssetTag": "Sprint130065", "SerialNumber": "Sprint130065", "AssetType": "Device", "LoanOrGiveaway": "Loan", "ManufacturerName": "Acer", "FormFactor": "Laptop|Tablet", "ModelName": "Aspire PC", "Configuration": "Aspire PC", "Quantity": 1, "AssetUID": "Aspire PC", "GroupName": "SubTwoPublicGroup01", "LocationName": "SubTwoPublic01Location01", "IsAvailable": "No", "Status": "Active", "Notes": null403{"error":"API key is missing."}400{"error":"Please provide username."}400{"error":"Please provide password."}401{"error":"Invalid API key."}401{"error":"Incorrect username or password."}500{"error":"Something went wrong. Please try again."}Query ParametersIdentify query parameters that apply to all API operations. For example, Below is a list of standard query parameters. These names are reserved in our REST APIs.ParameterMeaningNoteaccess_tokenOAuth 2.0 token for the current user.token_type“bearer”expires_inTime in secondsStatus CodesThe API uses the following HTTP status codes. 2XX – Success; 4XX - Error in client; 5XX - Error in server.Status CodeDescription200OK201Created202Accepted (Request accepted, and queued for execution)400Bad request401Authentication failure403Forbidden404Resource not found405Method Not Allowed409Conflict412Precondition Failed413Request Entity Too Large500Internal Server Error501Not Implemented503Service UnavailableAdditional Sample Request/Response SupplierAssetsCheckIn (AssetNotFound) If Check-in quantity greater than Checked out quantity Request Body: requestId : 38529 assetsToCheckIn : [ { "AssetId": 220, "AssetType": "AssetNotFound", "CheckInQuanity": 2 }]Response Body:{ "IsSuccess": false, "ErrorMessage": { "Quantity checked-in is invalid for this asset.": [ "220" ] }}If given the wrong AssetId for a requestRequest Body: requestId : 38529 assetsToCheckIn : [ { "AssetId": 223, "AssetType": "AssetNotFound", "CheckInQuanity": 2 }]Response Body:{ "IsSuccess": false, "ErrorMessage": { "Asset doesn't exist for this request.": [ "223" ] }If Check-in quantity is not givenWhen successfully saved, the message returns trueIf Multiple assets were given (both valid and invalid) – returns the response asRequest Body: requestId : 38529 assetsToCheckIn : [ { "AssetId": 50425, "AssetType": "Device", "CheckInQuanity": 1 },{ "AssetId": 50430, "AssetType": "Device", "CheckInQuanity": 10 },{ "AssetId": 50474, "AssetType": "Device", "CheckInQuanity": 4 }]Response Body:{ "IsSuccess": false, "ErrorMessage": { "Asset doesn't exist for this request.": [ "50430", "50474" ], "Quantity checked-in is invalid for this asset.": [ "50425" ] }}InStockAssetsCheckIn Entering the AssetId’s which were not existing in that requestRequest Body RequestId : 38573checkinModel :{ "AssetIds": [ 8601, 8605, 8609 ], "AssetTags": [ ]} Response Body{ "IsSuccess": false, "ErrorMessage": { "Asset doesn't exist for this request.": [ "8609" ] }}Entering all the correct AssetId’s or AssetTAGSRequest Body RequestId : 38573checkinModel : { "AssetIds": [ 8601, 8605 ], "AssetTags": [ "34Test00134","34Test00137" ]} Response Body{ "IsSuccess": true}CheckOut Request With Supplier Assets in the Request, no PO Number – Gives error msgResponse Body{ "IsSuccess": false, "ErrorMessage": "Transaction number is not valid."}With Supplier Assets and single supplier Parameters:requestId : 38567poNumber : sdafsfResponse Body:{ "IsSuccess": true}GLIMR, Supplier Assets and multiple suppliers (RequestId : 38568)Request Body:requestId : 38568poNumber : sdfewfwResponse Body:{ "IsSuccess": false, "ErrorMessage": "Multiple Suppliers Associated Request cannot be checkedout."}With No Suppliers, RequestID (38573)Request Body:requestId : 38573Response Body:{ "IsSuccess": true}Close Request As this request is already closed, it returns false.Request BodyrequestId : 38573Response Body{ "IsSuccess": false} ................
................

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

Google Online Preview   Download