JsonDispatch

A specification for building APIs in JSON based format for application-level communication.

What? Why?

• JsonDispatch is a specification that follows/merges rules for how a JSON response should be formatted while doing communication using REST apis.
• Though there is 1/2 spec available, but after doing several APIs it turns out, every spec (currently observed) lacks something. And the biggest issue is consistency.
• For backend developer (as I'm) it is really hectic to adopt new structure/element everytime (also for "need additional data" thing)
• Why this?
  • Better adaptation capability
  • Covering most of the possible scenario without breaking it
  • Cross-referencing for log detection/backtrace
  • Backward compatible (never remove, only add)

Let's explain with example

Example

Success response

{
    "signature": "60c1bbca-b1c8-49d0-b3ea-fe41d23290bd",
    "version": "1",
    "status": "success",
    "message": "Data prepare successful",
    "data": {
        "type": "articles",
        "source": "self",
        "attributes": {
            "category": 1,
            "sample1": [...],
            "sample2": [...],
        }
    },
    "_references": {
        "category": {
            "1": "One Production",
            "2": "Their Production",
            "3": "Our Production",
            "4": "Out of Sight"
        }
    },
    "_properties": {
        "data": {
            "type": "object",
            "name": "On the road",
            "template": "https://github.com/abmmhasan/sample-link"
        },
        "sample1": {
            "type": "array",
            "name": "Sample",
            "deprecation": "https://demo.link4"
        }
    },
    "_links": {
        "self": "https://demo.link",
        "next": "https://demo.next"
    }
}

Failed response

{
    "signature": "f4b44a6e-d593-11ec-9d64-0242ac120002",
    "version": "1",
    "status": "fail",
    "message": "Invalid request",
    "data": [
        {
            "status": 403,
            "source": "/data/attributes/secretPowers",
            "title": "Secret Power issue!",
            "detail": "Editing secret powers is not authorized on Sundays."
        },
        {
            "status": 422,
            "source": "/data/attributes/volume",
            "title": "Volume issue!",
            "detail": "Volume does not, in fact, go to 11."
        }
    ],
    "_properties": {
        "data": {
            "type": "array",
            "name": "invalid-resource"
        }
    }
}

Error response

{
    "signature": "c043e23a-4b26-4a05-96c4-5c60fcc18d50",
    "version": "1",
    "status": "error",
    "message": "someMessageHere",
    "code": "additionalErrorCode",
    "data": [
        {
            "status": 500,
            "source": "reputation",
            "title": "The backend responded with an error",
            "detail": "Reputation service not responding after three requests."
        }
    ],
    "_properties": {
        "data": {
            "type": "array",
            "name": "reputation-resource-error"
        }
    }
}

Primary Parameters

Lets have a look at our parameter assignment per status:

Now lets get familiar by element:

** These parameters have more in-depth property type-hint. Check below!

In-depth explanation

version

• Versioning must follow Semantic Versioning.
• The version number of the structure change when it happened for the first time. For example, our project version is 2.5, but the API structure actually changed in version 1.9; so the version number should be 1.9 here.
• As of Semantic Versioning (major.minor.patch), existing structure can be modified according to versioning method:
  • patch & minor version change means we can fix issue with existing data (like linguistics change, add new Error Code for Code key etc.). Must be backward compatible.
  • minor version change means we can add new keys.
  • major version may change structure like converting some data.attribute member type from object to array or vice-versa etc.

data

Though it may hold any type of data but you must keep the type/structure same respecting version-url-method (respecting version rule as given above) combination.

• For success response it may hold any type of data as defined (array/object/string/bool/number). Though it's use is completely independent but if it is object or array of object then it is recommended to keep following structure in immediate child objects:

  Name	Type	Hint/Example
  type	string	An unique identifier for the object
  source	string	unique identifier for source for data in attribute e.g. self
  attributes	array, object	payload
  references	object	same as _references but specific to current memeber only (optional)
  properties	object	same as _properties but specific to current memeber only (optional)

  "data": [
      {
          "type": "articles",
          "source": "self",
          "attributes": [
              {
                  "title": "Rails is Omakase",
                  "category": 1
              },
              {
                  "title": "Rails is Omakase2",
                  "category": 4
              },
              {
                  "title": "Rails is Omakase3",
                  "category": 1
              }
          ],
          "references": {
              "category": {
                  "1": "One Production",
                  "2": "Their Production",
                  "3": "Our Production",
                  "4": "Out of Sight"
              }
          },
          "properties": {
              "type": "array",
              "name": "c_title",
              "template":"https://some.link" ,
              "deprecation": "https://demo.link4",
              "count": 3,
              "range": "1000-1200",
              "page": 52
          }
      }
  ]

• For fail response it will hold array of objects explaining the reason (optional), as following:

  Name	Type	Hint/Example
  status	int	Explain error as HTTP code
  source	string	Path to element from root (glued by slash) where error detected (optional if parsing issue)
  title	string	A formal title for the reason (optional)
  detail	string	A detail explanation

  "data": [
      {
          "status": 403,
          "source": "/data/attributes/secretPowers",
          "title": "Secret Power issue!",
          "detail": "Editing secret powers is not authorized on Sundays."
      },
      {
          "status": 422,
          "source": "/data/attributes/volume",
          "title": "Volume issue!",
          "detail": "Volume does not, in fact, go to 11."
      }
  ]

• For error response it will hold array of objects explaining the reason (optional), as following:

  Name	Type	Hint/Example
  status	int	Explain error as HTTP code
  source	string	Provide source of error. E.g. self or google or ... (external source)
  title	string	A formal title for the reason (optional)
  detail	string	A detail explanation

  "data": [
      {
          "status": 500,
          "source": "reputation",
          "title": "The backend responded with an error",
          "detail": "Reputation service not responding after three requests."
      }
  ]

_references

Sometimes we may need to send some extra information regarding data parsing. & that is where it comes in. You can also think of it as normalizer that holds some defination/key-value resolver to parse data.

• This object will have key which client should be aware of,

• Anywhere the key name matches, will be resolved as key-value pair

• These keys will be resolved as value assigned here. E.g. We have data as given below. So any id/reference we get in attributes.category inside data object should be parsed accordingly. Like, if we get "1" we will parse as "One Production".

• It can even be a group of object / array as well under those keys depending on use case scenario.

  "_references": {
      "category": {
          "1": "One Production",
          "2": "Their Production",
          "3": "Our Production",
          "4": "Out of Sight"
      }
  }

_properties

This actually holds identity/property of groups inside data. Key-value pair is parsable as like _references but the value section have several things in it.

** You can add more memebers as you see fit

"_properties": {
    "data": {
        "type": "array",
        "name": "c_title",
        "template":"https://some.link" ,
        "deprecation": "https://demo.link4",
        "count": 10,
        "range": "102-890",
        "page": 52
    }
}

_links

Provide all the required links here, which can be used for reference, pagination, additional info, ...

• If pagination links required we can send relative paths as self, next, previous, first, last
• If we need to send reference e.g. author link, we can send author
• & much more as you see fit.

"_links": {
    "self": "https://link.to",
    "next": "https://link.next"
}