How to Model JSON Representation Format

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 popularly used JSON representation.
In a previous post, we learned - 
Most the time we use JSON as the format for displaying a resource. Let's understand what is naming convention for JSON field names

JSON Field name

It is recommended to use “lower camel case” as the JSON field name. It is recommended on considering its compatibility with JavaScript, which is assumed as one of the client applications. The JSON sample with field name set in “lower camel case”, is as given below. In “lower camel case”, the first letter of the word is in lowercase and subsequent first letters of words are in uppercase.
{
    "memberId" : "M000000001"
}

NULL and blank characters

It is recommended to differentiate NULL and blank characters as JSON values. Although, as the application process, NULL and blank characters are often equated, it is advisable to differentiate NULL and blank characters as the value to be set in JSON. 
Example: JSON sample wherein NULL and blank characters are differentiated.
{
    "dateOfBirth" : null,
    "address1" : ""
}

Date format

It is recommended to use the extended ISO-8601 format as the JSON date field format. Format other than extended ISO-8601 format can be used. However, it is advisable to use the extended ISO-8601 format, if there is no particular reason otherwise. There are two formats in ISO-8601 namely, basic format and extended format, however, readability is higher in an extended format. Basically, there are the following three formats.
  1. yyyy-MM-dd
{
    "dateOfBirth" : "1977-03-12"
}
   2. yyy-MM-dd’T’HH:mm:ss.SSSZ
{
    "lastModifiedAt" : "2014-03-12T22:22:36.637+09:00"
}
  1. yyyy-MM-dd’T’HH:mm:ss.SSS’Z’ (format for UTC)
{
    "lastModifiedAt" : "2014-03-12T13:11:27.356Z"
}

Hypermedia link format

It is recommended to use the following format to create a hypermedia link.
A sample of recommended format is as given below.
{
    "links" : [
        {
            "rel" : "ownerMember",
            "href" : "http://example.com/api/v1/memebers/M000000001"
        }
    ]
}
  • Link object consisting of 2 fields - "rel" and "href" is retained in collection format.
  • Link name for identifying the link is specified in "rel".
  • URI to access the resource is specified in "href".
  • "links" is the field which retains the Link object in collection format.

The format at the time of error response

You can follow below is an example of the response format when an error is detected.
{
  "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,
  • Error code (code)
  • Error message (message)
  • Error details list (details) are provided as error response formats. It is assumed that the error details list is used when input validation error occurs. It is a format that can retain details like the field in which the error occurred and the information of the error.

Sample JSON Representation

{
  "links" : [ {
    "rel" : "self",
    "href" : "http://localhost:8080/rest-api-web/api/v1/members/M000000001"
  } ],
  "memberId" : "M000000001",
  "firstName" : "John",
  "lastName" : "Smith",
  "genderCode" : "1",
  "dateOfBirth" : "2013-03-14",
  "emailAddress" : "[email protected]",
  "telephoneNumber" : "09012345678",
  "zipCode" : "1710051",
  "address" : "Tokyo",
  "credential" : {
    "signId" : "[email protected]",
    "passwordLastChangedAt" : "2014-03-14T11:02:41.477Z",
    "lastModifiedAt" : "2014-03-14T11:02:41.477Z"
  },
  "createdAt" : "2014-03-14T11:02:41.477Z",
  "lastModifiedAt" : "2014-03-14T11:02:41.477Z"
}

Conclusion

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

Related Posts

Comments