Messages consist of requests from the client to the ZOLOZ server and responses from the ZOLOZ server to the client. This topic describes the structure of both requests and responses.

Request structure

A request is a standard HTTP request composed of a Request-URI, method, header, and body. The following diagram shows the structure of an HTTP request.

Request-URI

Specifies the resource to apply the request to. The format is /api/{version}/{restfulPath}, where:

version is the interface version, for example, v1.
restfulPath is the path to the interface.

Request method

Only POST is accepted.

Request header

The request header carries additional information about the request and the client. The following table lists all header fields in the ZOLOZ gateway protocol.

Header field	Required	Description
Request-Time	Yes	Timestamp of the request
Content-Type	Yes	Media type of the request body
Client-Id	Yes	Unique client identifier assigned by ZOLOZ
Signature	Yes	RSA256 digital signature of the message
Encrypt	No	Encryption metadata, present only when the request body is encrypted

Request-Time (Required)

The timestamp of the request. The value combines two parts:

A date/time string following the RFC 3339 datetime standard
A timezone string following the RFC 822 timezone standard

Example: 2019-04-04T12:08:56+0530

Content-Type (Required)

The media type of the request body sent to the ZOLOZ server. Two content types are supported:

application/json; charset=UTF-8: use when the request is not encrypted.
text/plain; charset=UTF-8: use when the request is encrypted.

For details, see RFC 7231.

Client-Id (Required)

The client identifier assigned by ZOLOZ. This ID is generated upon account creation and is guaranteed to be unique for each client. The value is a 16-digit string.

Signature (Required)

The digital signature of the message. The value is a comma-separated list of two key-value pairs:

algorithm: the signing algorithm. Only RSA256 is accepted.
signature: the signature content, Base64-encoded.

The following example shows a valid Signature header field.

signature: algorithm=RSA256, 
signature=IpmAgtDqkjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCkw==

For details about signing requests and validating signatures, see Message signing and signature validation.

Encrypt (Optional)

Encryption information for the message. Present only when the request body is encrypted. The value is a comma-separated list of two key-value pairs:

algorithm: the encryption algorithm. Only RSA_AES is accepted.
symmetricKey: the AES key encrypted with RSA, Base64-encoded.

The following example shows a valid Encrypt header field.

encrypt: algorithm=RSA_AES, 
symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

For details about encrypting and decrypting requests, see Message encryption and decryption.

Request body

The request body carries the input parameters for an API call. The format depends on whether encryption is used:

Without encryption, the body is a JSON string. Set the Content-Type header field to application/json.
With encryption, the body is a Base64-encoded string of the encrypted data. Set the Content-Type header field to text/plain.

For the detailed content structure, refer to the API specification for each API.

Full HTTP request examples

The following examples show complete HTTP requests for both unencrypted and encrypted bodies.

Unencrypted request example

POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m

{
  "title": "hello",
  "description": "just for demonstration."
}

Encrypted request example

POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: text/plain; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m
Encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

r8w8wbc8Nv6sC2meJzArtGjDkbiAzg55UaDiq7TId1a7uzcv18qpOxVkXvqa3q/6TPemDDItZ79oHMzDJyvAngYqfpZZaedArWPCDeddqUl62zU5VwaB1NVhNmjHLNQ6bA1LxpsnMGnb6n8iWAEU4MtJ3TpXerMY6RToSBbI/IBA4MJFbXds0z6XLqQh9XNrLL/J0FUSV0XGFiBRxVMvUP2ytzEKh9HE6fqX/ZqTqadtp89PRTJZM87Rkb3oPdJAlaM7JUaIznGrtKe45UwjtrdYk86QhOmpWXj4L2g0Gww=

Response structure

A response from ZOLOZ is a standard HTTP response composed of an HTTP status, header, and body. The following diagram shows the structure of an HTTP response.

HTTP status

Indicates the processing status of a request. ZOLOZ uses standard HTTP response codes. For details, see RFC 7231.

Response header

Trace-Id

A unique ID generated for each API call, used for tracing and debugging.

Response-Time

The timestamp of the response. The value combines two parts:

A date/time string following the RFC 3339 datetime standard
A timezone string following the RFC 822 timezone standard

Example: 2019-04-04T12:08:56+0530

Content-Type

The media type of the response body. Two content types are supported:

application/json; charset=UTF-8: returned when the response is not encrypted.
text/plain; charset=UTF-8: returned when the response is encrypted.

For details, see RFC 7231.

Signature

The digital signature of the message. The value is a comma-separated list of two key-value pairs:

algorithm: the signing algorithm. Only RSA256 is accepted.
signature: the signature content, Base64-encoded.

The following example shows a valid Signature header field.

signature: algorithm=RSA256, 
signature=QexLgtKpdjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCky++

For details about signing responses and validating signatures, see Message signing and signature validation.

Encrypt

Encryption information for the message. Present only when the response body is encrypted. The value is a comma-separated list of two key-value pairs:

algorithm: the encryption algorithm. Only RSA_AES is accepted.
symmetricKey: the AES key encrypted with RSA, Base64-encoded.

The following example shows a valid Encrypt header field.

encrypt: algorithm=RSA_AES, 
symmetricKey=HnI+keXgI9eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC00++

For details about encrypting and decrypting responses, see Message encryption and decryption.

Response body

The response body carries the output parameters of an API call. The format depends on whether encryption is used:

Without encryption, the body is a JSON string. The Content-Type header field is set to application/json.
With encryption, the body is a Base64-encoded string of the encrypted data. The Content-Type header field is set to text/plain.

For the detailed content structure, refer to the API specification for each API.

Full HTTP response examples

The following examples show complete HTTP responses for both unencrypted and encrypted bodies.

Unencrypted response example

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15+0800
Signature: algorithm=RSA256, 
signature=SGnqy/sC1sbrfK+jAl0ATJwtqUg4jUhkqpPheEYPgnM+20P69NsdrL8BB/ml5ehfFVzsst1bzwEYpDNZvqqNSBo2BPVg78pjJEk0GGNIu7NQ/pyRncYy3pIIXvr91lIvINysHcw8AgUEXRLtjMf1ktQN2OsA3+OFKB6Cf7BrKNnxjeF1lSjzbTk2ua+z1unGHUOeA9GBloSL3rL8ngC/Zqn24/eHWyKJrMFnq1jv+IhOVCqeY4knVFcPgp/bFBs4gyTdE1G1fCK5xmzk9Co8dK0wr6KcC872evBGz7SCMYZCn6Y8O5uRqS9I6F26yKKdqw8PZv2rlwJFsX21l7wRSQ==

{
  "title": "hello",
  "description": "just for demonstration."
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}

Encrypted response example

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Response-Time: 2019-02-23T01:45:57+0000
Signature: algorithm=RSA256, 
signature=imNNW52LHemfAiUFqek4QQg3ZkdHBGEUOs2SBx0OxPGBIBC0bmpu0%2BviBH%2Bh9w86VTooveJmKQSBVIf0i7hQWXqyd5Qibz49d4k9AhIhTjBKQF1VZTlJUrlphWvisSa9zn5wl3P74v9Z4CDVvHfL3wZzfwg8ujo13nSYjYdsswhSZwkGUgkSCDjq2ObtsPMHG6ZRuzrTjW6tCrqTe6EY4HyHg1mWnsAj12i1b%2FnKNayP%2FCpAe%2BT0%2Fn66NeLGjR9hjTYJ8XKKNoZ5vW%2BVYjWiDt8XWSb3KEO2Zh5Cofswe85sVPnk2S%2BvbN0nlPNU0zlJJJK6ifoSyl%2FSKI6Siu05xw%3D%3D
Encrypt: algorithm=RSA_AES, symmetricKey=eXhw3n3fdpfruNv2kh9cJQ4NzqhNhjKjCynAu6Kn92p0WPY77d8DHJV5Y4QE9fShsW%2FYZIVhCtiZSC2bBS%2F1m9HnCwhKiWzKWTwo44J692DU%2B24Yty%2FHTalqD7QWoOOd0HCskrKFHgf4INE9PMskGnZbp4B7yuLmaUEtuo8FIFNB4e%2FCIL1DhBMdsgcYL%2FiWLylNbpXztE8kMVjoEeOsz%2FbBr3Z22A4%2BQveAIDEc5sr9cjkzCB2gJsjNt4bZUWiZfP8BPLV0QEEh9mhmqzprNao2x9DsuShFcjyc3db%2BZcbMOuI8NxI0V%2FwTDi23%2BloH6Q1Mg0QgWFORlJG9da8s7Q%3D%3D

0JR682PMFgoc2ttribGxpl3f/7rNvjwpmoaAvahki1RxWUSO6mKxyQf87OUgQxQULGabLL4Q5vjFx8XvW/ugvpFexfqLojDeMgNMTyJpkT8=