This article describes how you get started with the SystemWeaver REST API once it has been installed and configured. 


Prerequisites


The SystemWeaver REST API can be used to access your SystemWeaver server through an HTTP-based interface. The SystemWeaver REST API is still under development and new features are added every release.


Finding the REST API server

Contact your organization's IT department to get the URL of the SystemWeaver REST API for your SystemWeaver server.

Authenticating Towards the SystemWeaver Server

The SystemWeaver REST API uses basic HTTP authentication and OAuth 2.0 to authenticate users. 


Important Note: It is strongly recommended that HTTPS is used for the REST API. If not used, user credentials will be sent in clear text between the clients and the REST server.


When logging in, the user provides username and password (Note: Most special characters are supported. "&" is not supported). If the credentials are accepted, a token will be provided. A refresh token is also supplied with the response. The refresh token is used for prolonging the access token time.


Retrieving a Token

The below examples show a server authentication request using curl where the server is located on the URL: http://sys76:9000. 


The token itself can be retrieved from {URL}/token:


Using Username and password:

curl -X POST http://sys76:9000/token -d 'username=fredrik.systemite&password=test&grant_type=password'

Using Windows network authentication: 

curl -X POST https://localhost:9000/token -d 
"username=student&password=
test&windowsauthentication=true&grant_type=password"

If successful, it produces a response on the following form containing an access token and a refresh token:

{"access_token":"AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAZIzMKT_UMU6BqHdaJYNmigAAAAACAAAAAAADZgAAwAAAABAAAABLiECOrM3COk42PmO0cYWsAAAAAASAAACgAAAAEAAAAJAxZUh0GEQCen7DvWN-qrSwAAAAAAEwnDyoRNz1JFO9DBEsOvWZ6TG23DkOfWMP34LV-esxHNMpTXY81dcwlTk3EuMCq3tIcUFKxCOdVtY_BstcgI2NEaEnoyOTyR9qBHtND_lMRqFWBF-lhyNNu-9ey5q272rs9vBcJ59H4-sHzKqLtlu2_wd12zzquUF9pJ4ERfLNc2tr0wyxB4vbhgJrGmFCsqQjlcBMkHRRgWAfu1RB00e5pH3g6mTa91bpyGZ_3UIUAAAAVtKrhBNXPe7LjWQzMta7KFZdWHY",
"token_type":"bearer",
"expires_in":119,
"refresh_token":"1b5a6146-8591-49c0-b4b2-9b9a0754efab"}

Retrieving a New Token Using Refresh Token

The below example shows how to use the refresh token from the response above to acquire a new access token. The response has the same format as when retrieving a token the first time:

curl -X POST http://sys76:9000/token -d  'grant_type=refresh_token&refresh_token=1b5a6146-8591-49c0-b4b2-9b9a0754efab'
Note: When logging in using the SystemWeaver REST API, the connection will be reserved for the duration of the refresh token's expiration time which is ten minutes.

Retrieving an Item Resource

The below example shows how to retrieve information about an Item for a given handle using the access token from the login example:

curl -X GET http://sys76:9000/restapi/items/x04000000000000B7 -H 'Authorization: Bearer AQAAANCMnd8BFdERjHoAwE_Cl-sBAAAAZIzMKT_UMU6BqHdaJYNmigAAAAACAAAAAAADZgAAwAAAABAAAABLiECOrM3COk42PmO0cYWsAAAAAASAAACgAAAAEAAAAJAxZUh0GEQCen7DvWN-qrSwAAAAAAEwnDyoRNz1JFO9DBEsOvWZ6TG23DkOfWMP34LV-esxHNMpTXY81dcwlTk3EuMCq3tIcUFKxCOdVtY_BstcgI2NEaEnoyOTyR9qBHtND_lMRqFWBF-lhyNNu-9ey5q272rs9vBcJ59H4-sHzKqLtlu2_wd12zzquUF9pJ4ERfLNc2tr0wyxB4vbhgJrGmFCsqQjlcBMkHRRgWAfu1RB00e5pH3g6mTa91bpyGZ_3UIUAAAAVtKrhBNXPe7LjWQzMta7KFZdWHY'

Examples

The following articles provide examples of the most common methods. 


REST API Patch and Post Examples

REST API Get Examples


REST API Documentation

The SystemWeaver REST API uses Swashbuckle to generate API documentation. The documentation can be accessed in a web browser from {url}/documentation. Example: http://localhost:5555/documentation/



Note: The documentation does not load in Internet Explorer because support for it has been dropped in Swagger UI which is used for the documentation.