Web API is a framework that makes it easy to build and expose API connections over HTTP(s). Web API is used when you build RESTful applications running in a browser, or for integration when a server is communicating with other servers.
Simple web API example:
using System.Web.Http;
[RoutePrefix("api/samples")]
public class SampleApiController : ApiController
{
[Route("")]
[HttpGet]
public IHttpActionResult GetSampleData()
{
return Ok(new
{
Data = new[]
{
"item1",
"item2",
"item3"
}
});
}
}
Security
When using web API it is important to ensure that only authorized calls can execute the endpoints that are created. Some endpoints can allow anonymous user access because they are used in the public web application. Other endpoints are secured and access is limited to specific groups of users.
Preferred is to use HTTPS for all web API calls to ensure that communication can’t be tampered with.
When servers are communicating the JWT (JSON Web Token) authorization should be used to avoid sending username and password with each request. When the JWT expires, you need to request a new JWT with either the username and password or with a refresh token, depending on application and setup.
To restrict a web API endpoint to only use JWT the class or method should be declared with the OnlyJwtAuthorizationAttribute.
[Litium.Web.WebApi.OnlyJwtAuthorization]
public class SampleApiController : ApiController
Service Account
A service account is used to secure integrations where another system is connected directly to Litium.
When you create integrations to Litium you can let the consumer identify as a real user (person) in Litium or by using the service account. The benefit of using the service account over a real user account is that the service account is not allowed to login on the public site or back office, but can still have the same permissions as an administrator.
Service accounts are managed in back office, Settings > System settings > Service accounts. Each service account has a username and password that is used for identification.
Authorization
OAuth2 authorization flow for client credentials is used to create the JWT. With this flow the username and password is sent to the server and a JSON answer is returned with the JWT as an access token, along with information about when the token expires. The token can be reused for multiple requests until the token expires.
The token endpoint used in a POST request to create the JWT is https://domain/litium/oauth/token, and the required payload is “grant_type=client_credentials&client_id=[service account id]&client_secret=[service account password]”.
Example
Request
POST /Litium/OAuth/token HTTP/1.1
Host: domain
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=user&client_secret=password
Response
{
"access_token": "J4HlhawWVlIse-7-CwlqlFLVBtS1YBw01sXLzFuLehJt6JVWkJjQ236EbyRw7L5cSDC5opv9AmS7eu7fZRFUQ2Jy9
dyGbZiI3MahSYQTjoZ3NsaRwNL6NYF2SRqZlxKk7Hf8pjgca2eui2mEbo4u2qFowzWrP6I8PNckyFB91t-6oM6fNqwB08DOCzvPxYQNKMFB6hz
1BHvv7xswFvrVRl_8fFTy5pRPN5cbCEButL-lJIJqm0fl193g2g9I_HvBDc6FFlcfx6t_ecG-V3xpmfInFjROm1o8yA6h8nCfsxbnQm2Q0aVYw
Lye22tCienKME3dL9yJy1cmRYXkJ7BH-rvaqlnG4BSc948GtjIxI3k6P1kWLG1hYskFGS0oancj",
"token_type": "bearer",
"expires_in": 599
}
In subsequent calls to the server the access token is sent as an authorization header in the request, the authorization type should be Bearer.
Token usage example request
GET /api/example/productlist HTTP/1.1
Host: domain
Content-Type: application/json
Authorization: Bearer J4HlhawWVlIse-7-CwlqlFLVBtS1YBw01sXLzFuLehJt6JVWkJjQ236EbyRw7L5cSDC5opv9AmS7eu7fZRFUQ2Jy9
dyGbZiI3MahSYQTjoZ3NsaRwNL6NYF2SRqZlxKk7Hf8pjgca2eui2mEbo4u2qFowzWrP6I8PNckyFB91t-6oM6fNqwB08DOCzvPxYQNKMFB6hz
1BHvv7xswFvrVRl_8fFTy5pRPN5cbCEButL-lJIJqm0fl193g2g9I_HvBDc6FFlcfx6t_ecG-V3xpmfInFjROm1o8yA6h8nCfsxbnQm2Q0aVYw
Lye22tCienKME3dL9yJy1cmRYXkJ7BH-rvaqlnG4BSc948GtjIxI3k6P1kWLG1hYskFGS0oancj