Overview

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-Id header. Any duplicate Request-Id will return http status 409 Conflict.