Overview
The external WebApi is a typical and easy to use RESTAPI which provides spare part and product information.
Versioning guideline
The HTTP API is versioned with 'URI Versioning'. That means the version info is part of each endpoint.
For versioning we use only a MAJOR version. The version schema follows the this scheme:
The schema is: ../v{apiVersion}/..
<the api base url>/api/v{apiVersion}/productHow to use the API
The API request must include both api and the api version.
Valid API request
The following is a example of a request to the production endpoint https://induflow.boschrexroth.com. In the following description we replace the endpoint with the placeholder <the api base url>:
curl -X 'GET' \
'<the api base url>/api/v1/product' \
-H 'accept: application/json'Authentication
All API request requires authentication. You must authenticate with a bearer access token as a header prefix. The access token can be requested from our open id connect authority. Therefore you need a client id and a client secret. The client information can be requested from the developer team.
The token can requested from the open id connect authority:
| Key | Value |
|---|---|
OpenId Configuration |
https://p15.authz.bosch.com/auth/realms/dc5/.well-known/openid-configuration |
Flow |
clientCredentials |
With this information you can request a bearer token from our authority, now the token can be added to the header.
curl -X 'GET' \
'https:<the api base url>/api/v1/product' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your bearer Token>'If authentication information is not valid or is missing, an error message with status code of 401 Unauthorized will be returned.
If the authentication information is correct but you have not the role to execute the endpoint, an error message with status code of 403 Forbidden will be returned.
Authentication example for postman
Postman is a 3rd party program for using APIs.
The following properties must be set in Postman for authorization to receive a valid bearer token:
| Key | Value |
|---|---|
Type |
OAuth 2.0 |
Add auth data to |
Request Headers |
Use Token Type |
Access token |
Header Prefix |
Bearer |
Token name |
<choose a client name> |
Grant Type |
Client Credentials |
Access Token URL |
https://p15.authz.bosch.com/auth/realms/dc5/protocol/openid-connect/token |
Client ID |
<your client ID> |
Client Secret |
<your client secret> |
Scope |
openid |
Client Authenthcation |
Send as Basic Auth header |
Authentication example for Rest Client
Rest Client is a visual studio extension for using APIs.
The following code snippet creates a valid bearer token for authorization:
###############################################
# Get access token request
###############################################
@clientId = <insert a valid client id>
@clientSecret = <insert a valid client secret>
@scope = openid
@accessTokenUrl = https://p15.authz.bosch.com/auth/realms/dc5/protocol/openid-connect/token
# @name tokenrequest
POST {{accessTokenUrl}}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id={{clientId}}
&client_secret={{clientSecret}}
&scope={{scope}}
###
@accessToken = {{tokenrequest.response.body.access_token}}
###
###############################################
# Example requests
###############################################
### get product
GET {{<the api base url>}}/api/v1/product
Content-Type: application/json
Authorization: Bearer {{accessToken}}Status codes
The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
|---|---|
GET |
Access one or more resources and return the result as JSON. |
The following table shows the possible return codes for API requests.
| Return values | Description |
|---|---|
200 OK |
The GET request was successful, and the resource itself is returned as JSON. |
204 No Content |
The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. |
400 Bad Request |
A required attribute of the API request is missing. For example, the title of an issue is not given. |
401 Unauthorized |
The client isn’t authenticated. A valid client token is necessary. |
403 Forbidden |
The request isn’t allowed. For example, the client isn’t allowed to get a project. |
404 Not Found |
A resource couldn’t be accessed. For example, an ID for a resource couldn’t be found. |
422 Unprocessable |
The entity couldn’t be processed. |
500 Server Error |
While handling the request, something went wrong on the server. |
503 Service Unavailable |
The server cannot handle the request because the server is temporarily overloaded. |
Data validation and error reporting
When working with the API you may encounter validation errors, in which case the API returns an HTTP 422 error.
Such errors appear in the following cases:
-
A required attribute of the API request is missing (for example, the Id of an issue isn’t given).
-
An attribute did not pass the validation (for example, the id is not a valid object id).
When an attribute did not pass the validation, you receive something like:
HTTP/1.1 422 Unprocessable
Content-Type: application/json
{
"title": "One or more validation errors occurred.",
"status": 422,
"errors": {
"Id": [
"The specified condition was not met for 'Id'."
]
}
}
Unknown server error
If something unexpected happens the API the API returns an HTTP 500 error.
HTTP/1.1 500 Server Error
Content-Type: application/json
{
"Status": "Internal Server Error",
"Message": "An unexpected error occurred. Please contact the development team with the provided errorId if you are in need of further assistance.",
"ErrorId": "579b30f7-b507-4ff1-a531-663ea691730c"
}
File download
If the response is a byte array.
The file metadata will be returned in the response header.
{
content-disposition: {
"filename":file.png,
},
content-length: 10000
content-type: image/png
}
| Key | Type | Description |
|---|---|---|
content-disposition |
string |
Contains information about the filename. |
content-length |
long |
The current page size, the page size could be changed by the api if the requested page size greater than maximum page size. |
content-type |
string |
The mime type of the content. |
Pagination
If the response type contains a list of entries the api use pagination to divides the list into discrete pages. The viewer can determine the page size and page number. He can add the values for this as query parameters to the request. The maximum page size is specified by the server. If this is exceeded by the viewer, the maximum page size is automatically taken so that it cannot be exceeded. The query parameters are optional. If there are no query parameters the default values are used.
| Key | Type | Value | Default | Description |
|---|---|---|---|---|
PageNumber |
int |
1 - n |
1 |
The page number the viewer will be request. |
PageSize |
int |
1 - maximum page size |
Maximum page size |
The page size determines the maximum number of entries that can be listed on the page. If there are fewer entries, fewer entries will be displayed. |
The pagination metadata will be returned in the response header.
x-pagination: {
"TotalCount":34,
"PageSize":5,
"CurrentPage":1,
"TotalPages":7,
"HasNext":true,
"HasPrevious":false
}
| Key | Type | Description |
|---|---|---|
TotalCount |
long |
The total count of entries. |
PageSize |
long |
The current page size, the page size could be changed by the api if the requested page size greater than maximum page size. |
CurrentPage |
long |
The current page info. |
TotalPages |
long |
The total pages count with the given page size. |
HasNext |
bool |
Is 'true' if there are next pages otherwise 'false'. |
HasPrevious |
bool |
Is 'true' if there are prevoius pages otherwise 'false'. |