This page will help you get started with Job Offer Single Submission (JOSS) APIs
After reading this doc and its sub-docs, you will know how to:
- Generate signature as authentication method
- Integrate your application with JOSS APIs
Prerequisites
To use the information in this doc, you need to know:
- How RESTful APIs work, how to call them, and interpret their responses.
- Basic knowledge of how API authentication works.
General Background Details
This section covers common aspects to all JOSS APIs.
API Endpoints
As JOSS APIs are RESTful, users send HTTPS requests to URL addresses to call a command. JOSS APIs have two endpoints (common address prefixes for command URLs), one for staging calls and one for production calls. You also use different signature for authenticating staging and production requests, which we’ll cover in the Signature section.
- Staging:
<https://sandbox.joss.kemnaker.go.id> - Production:
<https://joss.kemnaker.go.id>
All JOSS API requests must use HTTPS. Any HTTP calls will be force redirect to HTTPS.
Request Headers
Every request to JOSS API have to have the following request headers
| Http Header | Required |
|---|---|
| Accept | For now only support for application/json and application/xml |
| Content-Type | This header required when use methods POST, PATCH, PUT. Currently only supported for application/json |
| Client-Id | Client ID retrieved from Indonesia Ministry of Man Power |
| Request-Id | Unique random string generated from client side to protect duplicate request |
| Request-Timestamp | Timestamp request on UTC time in ISO8601 UTC+0 format. It means to proceed with the transaction on UTC+7 (WIB), the client needs to subtract time with 7. Ex: to proceed with the transaction on September 22th 2022 at 08:51:00 WIB, the timestamp should be 2022-09-22T01:51:00Z |
| Signature | Security parameter that needs to be generated on client Backend and placed to the header request to ensure that the request is coming from a valid client |
Please refer to this section to generate the signature.
Http Response Code
| Status Code | Reason |
|---|---|
| 200 OK | When request is as per expectation |
| 201 Created | When request is as per expectation |
| 400 Bad Request | There is logic error |
| 401 Unauthorized | Invalid signature or the given signature has been expired |
| 403 Forbidden | The access token permission does not have permission to process the request |
| 404 Not Found | The specified resource does not exist |
| 422 Unprocessable Entity | Validation error |
| 429 Too Many Requests | Too many requests to server |
| 500 Internal Server Error | A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. You may retry the request in this case |
| 503 Service Unavailable | The server cannot handle the request for a service due to temporary maintenance. You may retry a little later in this case |
| 504 Gateway Timeout | The server cannot handle the request for a service due to loading of lots of data. You may retry a little later or shorten the time interval in this case |
All requests except for GET method should be unique identified by
Request-Idheader. Any duplicateRequest-Idwill return http status409 Conflict.