How to Model JSON Representation Format

Author:
This is the fourth step in Design Restful API. In this post, we will learn how to model JSON representation. There are many representations, but in this post, we mainly focus on the popularly used JSON representation.

In a previous post, we learned:

Most of the time, we use JSON as the format for displaying a resource. Let's understand the naming convention for JSON field names.

JSON Field Naming Convention

It is recommended to use lower camel case as the JSON field name. This naming convention ensures compatibility with JavaScript, which is often used as a client application. In "lower camel case," the first letter of the word is in lowercase, and subsequent first letters of words are in uppercase.

Example:

{
    "memberId": "M000000001"
}

Handling NULL and Blank Characters

It is recommended that NULL and blank characters be differentiated as JSON values. Although NULL and blank characters are often equated during application processing, it is advisable to distinguish between them in JSON.

Example:

{
    "dateOfBirth": null,
    "address1": ""
}

Date Format

It is recommended to use the extended ISO-8601 format as the JSON date field format. While other formats can be used, the extended ISO-8601 format is preferred due to its higher readability. The following are common formats:

  1. yyyy-MM-dd
    {
    "dateOfBirth": "1977-03-12"
}
  2. yyyy-MM-dd'T'HH:mm:ss.SSSZ
    {
    "lastModifiedAt": "2014-03-12T22:22:36.637+09:00"
}
  3. yyyy-MM-dd'T'HH:mm:ss.SSS'Z' (UTC format)
    {
    "lastModifiedAt": "2014-03-12T13:11:27.356Z"
}

A specific format is recommended for creating hypermedia links.

Example:

{
    "links": [
        {
            "rel": "ownerMember",
            "href": "http://example.com/api/v1/members/M000000001"
        }
    ]
}
  • The link object consists of two fields: "rel" and "href".
  • The name of the link to identify the link is specified in "rel".
  • The URI to access the resource is specified in "href".
  • "links" is the field that retains the link object in a collection format.

Error Response Format

Below is an example of the response format when an error is detected.

Example:

{
    "code": "e.ex.fw.7001",
    "message": "Validation error occurred on item in the request body.",
    "details": [
        {
            "code": "ExistInCodeList",
            "message": "\"genderCode\" must exist in code list of CL_GENDER.",
            "target": "genderCode"
        }
    ]
}

In the above example:

  • code: Error code
  • message: Error message
  • details: Error details list, which is used when input validation errors occur. It retains details like the field in which the error occurred and the information of the error.

Real-World Use Case: E-commerce Platform API

Let's apply these best practices to design an API for an e-commerce platform that manages products, categories, and orders.

Resources

  1. Product

    • GET /api/products - Returns a list of products
    • GET /api/products/{id} - Returns a specific product
    • POST /api/products - Creates a new product
    • PUT /api/products/{id} - Updates a specific product
    • DELETE /api/products/{id} - Deletes a specific product

  2. Category

    • GET /api/categories - Returns a list of categories
    • GET /api/categories/{id} - Returns a specific category
    • POST /api/categories - Creates a new category
    • PUT /api/categories/{id} - Updates a specific category
    • DELETE /api/categories/{id} - Deletes a specific category

  3. Order

    • GET /api/orders - Returns a list of orders
    • GET /api/orders/{id} - Returns a specific order
    • POST /api/orders - Creates a new order
    • PUT /api/orders/{id} - Updates a specific order
    • DELETE /api/orders/{id} - Deletes a specific order

Example JSON Representation for Product Resource

Example:

{
  "links": [
    {
      "rel": "self",
      "href": "http://localhost:8080/api/v1/products/P000001"
    }
  ],
  "productId": "P000001",
  "productName": "Wireless Mouse",
  "description": "A wireless mouse with ergonomic design.",
  "price": 29.99,
  "category": {
    "categoryId": "C0001",
    "categoryName": "Electronics"
  },
  "createdAt": "2024-07-09T10:15:30Z",
  "lastModifiedAt": "2024-07-09T10:15:30Z"
}

Error Response Example for Product Resource

Example:

{
  "code": "e.ex.pr.4001",
  "message": "Validation error occurred on product creation.",
  "details": [
    {
      "code": "RequiredField",
      "message": "\"productName\" is a required field.",
      "target": "productName"
    }
  ]
}

Conclusion

In this post, we have learned how to model JSON representation. In the next step, we will learn how to choose different HTTP status codes to return from the REST API.

Comments

Post a Comment

Leave Comment