{"info":{"_postman_id":"f6282f5e-e391-4691-b4a6-56b808b0f50f","name":"RHB API Documentation Improvement","description":"

📄 Brief Introduction on RHB's API Products

RHB's API Products is intended to empower innovation between developers and businesses by integrating RHB's banking services. The platform provides a suite of APIs that allow developers to access banking tools and automate processes such as mortgages, auto financing, credit cards and many more.

🔖 The Goal of This Documentation

RHB API Documentation Improvement Project

As RHB continues to innovate and expand its digital offerings (in parallel with its competitors), it’s crucial for RHB's API documentation to reflect the same level of clarity that developers expect from a top-tier financial institution.

The Importance of High-Quality API Documentation

In a competitive financial landscape, high-quality API documentation is essential for fostering innovation and driving adoption. Clear, concise, and developer-friendly documentation ensures that developers can easily integrate with RHB's services, reducing friction and accelerating time-to-market for new solutions.

The existing RHB API documentation has areas that could be improved to enhance readability, usability, and overall developer experience.

Project Goals

This project aims to bridge the gaps in RHB’s API documentation and make it more developer-friendly.

Key Focus Areas:

Clarity: Ensure the documentation is easy to understand, with clear explanations of endpoints, parameters, and responses.
\n
Usability: Organize the documentation logically, making it simple for developers to find the information they need.
\n
Practicality: Provide actionable and relevant examples to reduce friction and help developers get started quickly.
\n

Personal Contribution

While this effort isn’t a definitive solution, it serves as a meaningful step forward—at least for me, and hopefully for other developers who interact with RHB’s APIs.

Expected Outcomes:

Reduced friction for developers: Clearer documentation will help developers integrate with RHB’s APIs more efficiently.
\n
Enhanced developer experience: Improved usability will enable developers to focus on creating innovative financial solutions.
\n
Increased adoption: High-quality documentation will encourage more developers and businesses to leverage RHB’s APIs.
\n

By prioritizing clarity, usability, and practicality, this project aims to make RHB’s API documentation a more effective tool for developers, fostering innovation and driving the adoption of RHB’s digital services.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"📄 Brief Introduction on RHB's API Products","slug":"brief-introduction-on-rhbs-api-products"},{"content":"🔖 The Goal of This Documentation","slug":"the-goal-of-this-documentation"}],"owner":"41291950","collectionId":"f6282f5e-e391-4691-b4a6-56b808b0f50f","publishedId":"2sAYX3s3uu","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-02-03T03:42:46.000Z"},"item":[{"name":"RHB Handshake Authentication Improvement","item":[],"id":"480cccd2-25ae-401d-822c-99c33a95556d","description":"

Errors and Weaknesses

The RHB Handshake Authentication has several weaknesses and areas for improvement. Below is a detailed breakdown of the issues:

1. Lack of Clarity in Required Fields

The username and password fields are marked as false for Required, which is misleading. For authentication, these fields should be mandatory.
\n
Similarly, expiresAt and token in the response should be required since they are critical for JWT authentication.
\n

2. Inconsistent Response Codes

The response codes 200 OK and 201 Created are both used, but 201 Created is inappropriate for an authentication endpoint. A successful authentication should return 200 OK.

3. Missing Descriptions

The documentation lacks detailed descriptions for fields like expiresAt, token, and errorCode. This makes it difficult for developers to understand the purpose and format of these fields.

4. Ambiguous Error Handling

The ErrorResponse structure is reused for multiple error codes (e.g., 400, 401, 403, 404, 500), but there is no explanation of how the errorCode and errorDesc vary across these scenarios.

5. No Example Requests/Responses

The documentation does not provide concrete examples of requests and responses, which are essential for developers to understand how to use the API.

6. No Security Information

There is no mention of security requirements, such as HTTPS usage or rate limiting, which are critical for authentication APIs.

7. No Versioning Information

The API does not specify its version, which could lead to issues if the API evolves in the future.

8. Poor Organization

The documentation is not well-structured. Key details are scattered, and there is no clear flow from request to response.

9. Incomplete Definitions

The definitions section (ErrorObj, ErrorResponse, JwtRequest, JwtResponse) lacks detailed descriptions and examples, making it harder for developers to understand the data structures.

10. Unclear Default Values

The use of default in the documentation is ambiguous. It is unclear what the default values are for fields like password, username, expiresAt, and token.

By addressing these weaknesses, the documentation can be significantly improved to enhance readability, usability, and developer experience.

\n","_postman_id":"480cccd2-25ae-401d-822c-99c33a95556d"},{"name":"RHB Handshake Authentication Copy","item":[],"id":"da08ff3f-8a0e-44c1-ac62-968d4f0fbbe4","description":"

POST `/api/handshake/rhb-handshake/authenticate`

The RHB Handshake Authentication API enables users to authenticate and retrieve a JWT (JSON Web Token) for secure access to RHB services. This API is essential for applications requiring secure, token-based authentication. For more details on security best practices, refer to the Security Guidelines.

Request Parameter

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Required	Type	Description
`username`	Yes	string	The username for authentication.
`password`	Yes	string	The password for authentication.

Request Example

{  \n\"username\": \"[user@example.com](https://mailto:user@example.com)\",  \n\"password\": \"securePassword123\"  \n}\n\n

Status Codes and Errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Description
`200 OK`	Authentication successful. Returns a JWT token and its expiration time.
`400 Bad Request`	The request is invalid or malformed.
`401 Unauthorized`	Authentication failed due to invalid credentials.
`403 Forbidden`	The user does not have permission to access the resource.
`404 Not Found`	The requested resource does not exist.
`500 Internal Server Error`	An unexpected error occurred on the server.

Response Example

{\n    \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"expiresAt\": \"2023-10-01T12:00:00Z\"\n}\n\n

Error Parameter

All error responses follow the same structure:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Name	Type	Required	Description
`date`	string	No	Timestamp of the error.
`error`	object	No	Details of the error.
→ `errorCode`	int	No	A code representing the error type.
→ `errorDesc`	string	No	A description of the error.

Error Example

{\n    \"date\": \"2023-09-25T10:00:00Z\",\n    \"error\": {\n        \"errorCode\": 1002,\n        \"errorDesc\": \"Invalid username or password.\"\n    }\n}\n\n

\n","_postman_id":"da08ff3f-8a0e-44c1-ac62-968d4f0fbbe4"}],"event":[{"listen":"prerequest","script":{"id":"77828aaf-2183-499c-9755-8156b8feea93","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3ee90522-2a4c-4755-b6f1-d6c4b802aeea","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"https://farming-simulator.pstmn.io"}]}