api reference document - microsoft · web viewthe information provided in this document is provided...
TRANSCRIPT
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:
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
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
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
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)
11 | P a g e© GLIMR
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.
12 | P a g e© GLIMR
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,
13 | P a g e© GLIMR
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
14 | P a g e© GLIMR
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 [
15 | P a g e© GLIMR
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
16 | P a g e© GLIMR
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;
}
17 | P a g e© GLIMR
GLIMR 1.0
18 | P a g e© GLIMR
GLIMR 1.0
4. SupplierAssetsCheckInIdentify the resource (aka method) and describe its purpose.
4.1. Resource InformationThe resource information is as follows:
Method Purpose
Response formats JSON
Requires authentication? Yes
Rate limited? No
Requests -
4.2. Request The HTTP method and URL is as follows:
Method URL
GET https://glimrapi.azurewebsites.net/api/SupplierAssetsCheckIn
4.3. Parameters This API includes the following optional and required parameters:
requestId : 38529
assetsToCheckIn : [
{
"AssetId": 220,
"AssetType": "AssetNotFound",
"CheckInQuanity": 2
}
]
19 | P a g e© GLIMR
GLIMR 1.0
Name Type Description Required
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
}
Name Type Description
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
4.6.2. Sample ResponseIf successful, returns the HTTP status of 200 and a transaction object.
{ "IsSuccess": false, "ErrorMessage": "Invalid RequestID."
}
20 | P a g e© GLIMR
GLIMR 1.0
You can also use the following table to document the response.
Status Response
200 {
"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."}
21 | P a g e© GLIMR
GLIMR 1.0
5. AssetStatusReportIdentify the resource (aka method) and describe its purpose.
5.1. Resource InformationThe resource information is as follows:
Method Purpose
Response formats JSON
Requires authentication? Yes
Rate limited? No
Requests -
5.2. Request The HTTP method and URL is as follows:
Method URL
GET https://glimrapi.azurewebsites.net/api/AssetStatusReport
5.3. Parameters This API includes the following optional and required parameters:
Name Type Description Required
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
22 | P a g e© GLIMR
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
Name Type Description
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.
23 | P a g e© GLIMR
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
5.6.2. Sample ResponseIf successful, returns the HTTP status of 200 and a transaction object.
You can also use the following table to document the response.
Status Response
200 "AssetId": 43750,
"AssetTag": "Sprint130065",
"SerialNumber": "Sprint130065",
"AssetType": "Device",
"LoanOrGiveaway": "Loan",
"ManufacturerName": "Acer",
"FormFactor": "Laptop|Tablet",
"ModelName": "Aspire PC",
24 | P a g e© GLIMR
GLIMR 1.0
Status Response
"Configuration": "Aspire PC",
"Quantity": 1,
"AssetUID": "Aspire PC",
"GroupName": "SubTwoPublicGroup01",
"LocationName": "SubTwoPublic01Location01",
"IsAvailable": "No",
"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."}
25 | P a g e© GLIMR
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
26 | P a g e© GLIMR
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
27 | P a g e© GLIMR
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,
"AssetType": "AssetNotFound",
"CheckInQuanity": 2
}
]
Response Body:
{
"IsSuccess": false,
"ErrorMessage": {
"Quantity checked-in is invalid for this asset.": [
"220"
]
}
}
28 | P a g e© GLIMR
GLIMR 1.0
2) If given the wrong AssetId for a request
Request Body:
requestId : 38529
assetsToCheckIn : [
{
"AssetId": 223,
"AssetType": "AssetNotFound",
"CheckInQuanity": 2
}
]
Response Body:
{
"IsSuccess": false,
"ErrorMessage": {
"Asset doesn't exist for this request.": [
"223"
]
}
29 | P a g e© GLIMR
GLIMR 1.0
3) If Check-in quantity is not given
4) When successfully saved, the message returns true
30 | P a g e© GLIMR
GLIMR 1.0
5) If Multiple assets were given (both valid and invalid) – returns the response as
Request 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"
]
}
}
31 | P a g e© GLIMR
GLIMR 1.0
32 | P a g e© GLIMR
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": {
"Asset doesn't exist for this request.": [
"8609"
]
}
}
33 | P a g e© GLIMR
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
}
34 | P a g e© GLIMR
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}
35 | P a g e© GLIMR
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)
36 | P a g e© GLIMR
GLIMR 1.0
Request Body:
requestId : 38573
Response Body:
{
"IsSuccess": true
}
37 | P a g e© GLIMR
GLIMR 1.0
11. Close Request As this request is already closed, it returns false.
Request Body
requestId : 38573
Response Body
{
"IsSuccess": false
}
38 | P a g e© GLIMR