API Reference Document - Microsoft · Web viewThe information provided in this document is provided...

GLIMR APIDocumentation Version 1.0 ● 19 May 2023

MICROSOFT

GLIMR 1.0

Trademarks

Disclaimer

The 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 Lifetime

Microsoft 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:

[email protected]

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.

2 | P a g e© GLIMR

mailto:[email protected]

GLIMR 1.0

PrefaceIntended Audience

This 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 (https://glimr.cloudapp.net)

Table of Contents1. Overview.......................................................................................................61.1. Conventions...............................................................................................61.2. Current Version.........................................................................................61.3. Schema......................................................................................................61.4. HTTP Redirects.........................................................................................71.5. HTTP Requests..........................................................................................71.6. HTTP Methods...........................................................................................71.7. Authentication...........................................................................................81.8. Pagination..................................................................................................91.9. Rate Limiting.............................................................................................91.10. URL Format...............................................................................................92. API Reference Documentation...................................................................112.1. Overview..................................................................................................113. RequestStatusReport..................................................................................133.1. Resource Information..............................................................................133.2. Request....................................................................................................133.1. Parameters..............................................................................................133.2. Authorization...........................................................................................133.3. Response.................................................................................................143.1. Samples...................................................................................................154. SupplierAssetsCheckIn...............................................................................204.1. Resource Information..............................................................................204.2. Request....................................................................................................204.3. Parameters..............................................................................................204.4. Authorization...........................................................................................21

3 | P a g e© GLIMR

GLIMR 1.0

4.5. Response.................................................................................................214.6. Samples - CheckoutRequest....................................................................215. AssetStatusReport......................................................................................235.1. Resource Information..............................................................................235.2. Request....................................................................................................235.3. Parameters..............................................................................................235.4. Authorization...........................................................................................235.5. Response.................................................................................................245.6. Samples -.................................................................................................256. Query Parameters.......................................................................................277. Status Codes...............................................................................................288. Additional Sample Request/Response SupplierAssetsCheckIn (AssetNotFound)...............................................................................................299. InStockAssetsCheckIn................................................................................3510. CheckOut Request......................................................................................3711. Close Request.............................................................................................40

4 | P a g e© GLIMR

GLIMR 1.0

Document 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 Number

Revision Date Summary of Changes Author

v1 4-21-2017 Initial Document Release Glimr Team

v2 2/20/2018 Added more functionality Glimr Team

v3

Reference Documents None.

Distribution ListNone.

5 | P a g e© GLIMR

GLIMR 1.0

1. OverviewThe GLIMR Application has created a web API at https://glimrapi.cloudapp.net. 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.

1.1. 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.

1.2. Current VersionBy default, all requests receive the v1 version of the API.

1.3. SchemaAll API access is over HTTPS, and accessed from the https://glimrapi.azurewebsites.net/

All data is sent and received as JSON.

All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

Summary 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.

6 | P a g e© GLIMR

https://glimrapi.azurewebsites.net/

https://glimrapi.cloudapp.net/

GLIMR 1.0

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.

1.4. HTTP RedirectsStatus Code Description

301 Permanent 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, 307 Temporary 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.

1.5. HTTP Requests HTTP 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 arguments

HTTP Headers: Specifies attributes of the request, including authentication, encoding and request format

Request Body: Describes resources or specifies a call-control script

1.6. HTTP MethodsIdentify the methods used in this document.

The GLIMR API supports POST, GET methods.

1.6.1. POSTUpdates an existing resource.

Example:

POST /token

Updates an existing photo.

1.6.2. GETRetrieves an existing resource.

Example:

7 | P a g e© GLIMR

GLIMR 1.0

GET / api/RequestStatusReport

Retrieves all request for a given request status.

1.6.3. PUTExample:

/api/CloseRequest

1.7. Authentication

Here are the steps for authentication:

1. The client application sends a request to Authentication server endpoint with a credential.

2. If the username and password are found correct, then the Authentication server sends a token to the client as a response.

3. Token contains data to identify a user and an expiry time.4. Client application then uses the token to access the method/resources in

next requests while the token is valid

Sample Token Request using Postman:

Download postman as a part of Google chrome browser extension.

8 | P a g e© GLIMR

http://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_CloseRequest

http://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_GetRequestStatus

GLIMR 1.0

Requesting Token using Postman

Requesting resource with Token

1.8. PaginationNone

1.9. Rate LimitingNone

1.10.URL FormatThe API URL uses the following format:

<protocol>://<host>:<port>/api/<MethodName>

Example:

GET

https://glimrapi-uat.azurewebsites.net/api/RequestStatusReport?subsidiary=Ztest&requestStatus=New

9 | P a g e© GLIMR

GLIMR 1.0

2. API Reference DocumentationHere are the details of GLIMR API resources, their parameters, and code samples.

2.1. OverviewList of methods for GLIMRAPI

10 | P a g e© GLIMR

GLIMR 1.0

Note that the term method and resource (and object) tend to be used interchangeable in API documentation.

Method Purpose

RequestStatusReport

This API call returns all request with requested asset details for a given status

AssetStatusReport This API call returns all assets from specified sub/group

CloseRequest This API call will close the associated request.

CheckoutRequest This API will checkout the associated request

InstockAssetsCheckin

Checks in GLIMR assets by AssetId or Asset-Tag

SupplierAssetsCheckIn

Checks in Supplier assets by AssetId and AssetType (Device, Accessory, AssetNotFound)


https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_SupplierAssetsCheckIn

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_SupplierAssetsCheckIn

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_InstockAssetsCheckin

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_InstockAssetsCheckin

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_CheckoutRequest

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_CloseRequest

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_GetAssetStatusReport

https://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_GetRequestStatus


GLIMR 1.0

3. RequestStatusReport

3.1. Resource InformationMethod Purpose

Response formats JSON

Requires authentication? Yes

Rate limited? No

Requests -

3.2. Request HTTP method and the URL for API:

Method URL

GET https://glimrapi.azurewebsites.net/api/RequestStatusReport

3.1. Parameters This API includes the following optional and required parameters:

Name Type Description Required

subsidiary string Subsidiary Name Yes

requeststatus string Request Status Yes

group string Group Name No

3.2. Authorization This method takes Bearer token as a parameter to validate the request, and the token is valid for one day.



GLIMR 1.0

3.3. 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,


GLIMR 1.0

"QuantityReserved": 0, "AssetGroup": "TestGroup01", "AssetLocation": null, "IsSupplierAsset": "N", "SupplierName": "N/A" }]

Name Type Description

RequestId integer An ID that identifies this Request.

RequestStatusId integer An ID that identifies the request status.

RequestStatusName string A description of the request status.

RequestNeedByDate

datetime Date that requester expects assets.

RequestType string Type of Request (“Loan” or “Giveaway”).

GroupName string Name of Group fulfilling requested assets.

LocationName string Name of Location fulfilling requested assets.

Comments string Additional comments from Requester.

AgreementSent datetime Date/Time agreement sent

AgreementSigned datetime Date/Time agreement signed

AssetDetail JsonObject Contains details about each asset in Request

3.1. SamplesThis section provides samples requests and responses.

3.1.1. Sample RequestGET

http://glimrapi-uat.azurewebsites.net/api/AssetStatusReport?subsidiary=Ztest&assetStatus=Active&available=Yes


GLIMR 1.0

3.1.2. Sample 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.

Status Response

200 [


GLIMR 1.0

Status Response

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


GLIMR 1.0

static 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 = "http://glimrapi-test.azurewebsites.net/api/RequestStatusReport?subsidiary=xxxx&&requeststatus=new&group=xxxxx"

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;

}




GLIMR 1.0


GLIMR 1.0

4. SupplierAssetsCheckInIdentify the resource (aka method) and describe its purpose.

4.1. Resource InformationThe resource information is as follows:

Method Purpose



Rate limited? No

Requests -

4.2. Request The HTTP method and URL is as follows:

Method URL

GET https://glimrapi.azurewebsites.net/api/SupplierAssetsCheckIn


requestId : 38529

assetsToCheckIn : [

{

"AssetId": 220,

"AssetType": "AssetNotFound",

"CheckInQuanity": 2

}

]


GLIMR 1.0


requestId string Subsidiary Name Yes

assetsToCheckIn Model Object

(AssetId, AssetType, Checkinquantity)

Yes

4.4. Authorization If this request requires authorization, identify the following scopes

4.5. Response Describe the response body and the structure. For example

{

"IsSuccess": true

}


RequestId integer An ID that identifies this Request.

AssetIds Array An ID that identifies the asset ids.

AssetTags Array Asset Tag.

4.6. Samples - CheckoutRequestProvide samples requests and responses.

4.6.1. Sample RequestGET http://glimrapi.azurewebsites.net/api/CheckoutRequest?requestId=38567


{ "IsSuccess": false, "ErrorMessage": "Invalid RequestID."

}


http://glimrapi-uat.azurewebsites.net/swagger/ui/index#!/Request/Request_CheckoutRequest

GLIMR 1.0


Status Response

200 {

"IsSuccess": true

}






500 {"error":"Something went wrong. Please try again."}


GLIMR 1.0

5. AssetStatusReportIdentify the resource (aka method) and describe its purpose.

5.1. Resource InformationThe resource information is as follows:

Method Purpose



Rate limited? No

Requests -

5.2. Request The HTTP method and URL is as follows:

Method URL

GET https://glimrapi.azurewebsites.net/api/AssetStatusReport



subsidiary string Subsidiary Name Yes

available string Yes/No Flag Yes

assetStatus string Asset Status Yes

group string Group Name Yes

5.4. Authorization If this request requires authorization, identify the following scopes


GLIMR 1.0

5.5. 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": string


AssetId Int An ID that identifies this Asset.

AssetTag string A unique string that identifies this Asset to the organiztion.

SerialNumber string A unique string that identifies this Asset to the manufacturer.

AssetType string A description of the Asset type (device, accessory, other).

LoanOrGiveaway string Type of Asset (“Loan” or “Giveaway”).

ManufacturerName string Name of manufacturer.


GLIMR 1.0

FormFactor string Form factor of asset (laptop, tablet, etc.).

ModelName string Name of Model.

Configuration string Name of configuration.

Quantity int Current quantity of particular asset

AssetUID string Unique identifier of asset (eg., “belongs to Merch group”)

GroupName string Name of Group containing requested assets.

LocationName string Name of Location containing requested assets.

IsAvailable string Is Asset available (yes,no)?

Status string Description of Asset status

Notes string Addition notes about Asset

5.6. Samples - Provide samples requests and responses.

5.6.1. Sample RequestGET http://glimrapi.azurewebsites.net/api/AssetStatusReport?

subsidiary=Subsidiary02&group=SubTwoPublicGroup01



Status Response

200 "AssetId": 43750,

"AssetTag": "Sprint130065",

"SerialNumber": "Sprint130065",

"AssetType": "Device",

"LoanOrGiveaway": "Loan",

"ManufacturerName": "Acer",

"FormFactor": "Laptop|Tablet",

"ModelName": "Aspire PC",


GLIMR 1.0

Status Response

"Configuration": "Aspire PC",

"Quantity": 1,

"AssetUID": "Aspire PC",

"GroupName": "SubTwoPublicGroup01",

"LocationName": "SubTwoPublic01Location01",

"IsAvailable": "No",

"Status": "Active",

"Notes": null






500 {"error":"Something went wrong. Please try again."}


GLIMR 1.0

6. 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.

Parameter Meaning Note

access_token OAuth 2.0 token for the current user.

token_type “bearer”

expires_in Time in seconds


GLIMR 1.0

7. Status CodesThe API uses the following HTTP status codes. 2XX – Success; 4XX - Error in client; 5XX - Error in server.

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

409 Conflict

412 Precondition Failed

413 Request Entity Too Large

500 Internal Server Error

501 Not Implemented

503 Service Unavailable


GLIMR 1.0

8. Additional Sample Request/Response SupplierAssetsCheckIn (AssetNotFound) 1) If Check-in quantity greater than Checked out quantity

Request Body:

requestId : 38529

assetsToCheckIn : [

{

"AssetId": 220,


"CheckInQuanity": 2

}

]

Response Body:

{

"IsSuccess": false,

"ErrorMessage": {

"Quantity checked-in is invalid for this asset.": [

"220"

]

}

}


GLIMR 1.0

2) If given the wrong AssetId for a request

Request Body:

requestId : 38529

assetsToCheckIn : [

{

"AssetId": 223,


"CheckInQuanity": 2

}

]

Response Body:

{

"IsSuccess": false,

"ErrorMessage": {

"Asset doesn't exist for this request.": [

"223"

]

}


GLIMR 1.0

3) If Check-in quantity is not given

4) When successfully saved, the message returns true


GLIMR 1.0

5) If Multiple assets were given (both valid and invalid) – returns the response as

Request Body:

requestId : 38529

assetsToCheckIn : [

{

"AssetId": 50425,


"CheckInQuanity": 1

},

{

"AssetId": 50430,


"CheckInQuanity": 10

},

{

"AssetId": 50474,


"CheckInQuanity": 4

}

]

Response Body:

{

"IsSuccess": false,

"ErrorMessage": {


"50430",

"50474"

],

"Quantity checked-in is invalid for this asset.": [

"50425"

]

}

}


GLIMR 1.0


GLIMR 1.0

9. InStockAssetsCheckIn 1) Entering the AssetId’s which were not existing in that request

Request Body

RequestId : 38573

1. checkinModel :{2. "AssetIds": [3. 8601, 8605, 86094. ],5. "AssetTags": [6. 7. ]8. }

Response Body

{

"IsSuccess": false,

"ErrorMessage": {


"8609"

]

}

}


GLIMR 1.0

2) Entering all the correct AssetId’s or AssetTAGS

Request Body

RequestId : 38573

9. checkinModel : {10. "AssetIds": [11. 8601, 860512. ],13. "AssetTags": [14. "34Test00134","34Test00137"15. ]16.}

Response Body

{

"IsSuccess": true

}


GLIMR 1.0

10. CheckOut Request 1) With Supplier Assets in the Request, no PO Number – Gives error msg

Response Body

17.{18. "IsSuccess": false,

"ErrorMessage": "Transaction number is not valid."19.}

2) With Supplier Assets and single supplier

Parameters:

requestId : 38567

poNumber : sdafsf

Response Body:

{

"IsSuccess": true}


GLIMR 1.0

3) GLIMR, Supplier Assets and multiple suppliers (RequestId : 38568)

Request Body:

requestId : 38568

poNumber : sdfewfw

Response Body:

{

"IsSuccess": false,

"ErrorMessage": "Multiple Suppliers Associated Request cannot be checkedout."}

4) With No Suppliers, RequestID (38573)


GLIMR 1.0

Request Body:

requestId : 38573

Response Body:

{

"IsSuccess": true

}


GLIMR 1.0

11. Close Request As this request is already closed, it returns false.

Request Body

requestId : 38573

Response Body

{

"IsSuccess": false

}


API Reference Document - Microsoft · Web viewThe information provided in this document is provided...

Documents

Transcript of API Reference Document - Microsoft · Web viewThe information provided in this document is provided...