[ADP-81] MIME type naming convention

Guidance

• SHOULD follow naming convention as

  application/vnd.vvtk.{applicationId}.{resourceType}[.{modifier}][.{versioning}]+json

applicationId

• SHOULD use/register the same applicationId in the internal API portal(TBD).

resourceType

• SHOULD be the same as resource type name in singular form.

  GET https://{ALIVE-APP-DOMAIN/users
  
  200
  Content-Type: application/vnd.vvtk.alive-app.user.json

modifier

• The modifier part is optional.

• This is used to customize the resource if necessary. For example, sometimes we don’t need the full content of a resource; use the modifier to indicate we need a simpler format.

  applicatio/vnd.vvtk.alive-app3.user.simple.v1+json

  Please note that there’s no common naming for the modifier, you need to make it clean and human-understandable. MUST document the usage in the API document.

versioning

• The versioning part is optional.
• MAY NOT provide versioning while your API audience is less than COMPANY_INTENRAL.
• SHOULD provide versioning while your API audience is greater than COMPANY_INTERNAL.
• For COMPANY_INTERNAL audience, SHOULD consider your strategy while you are making BREAKING change to the resource. Email to developer groups is an option.
• The versioning should follow semver.

Design thinking

Since we define that most of our API response is in JSON format, it’s common to return Content-Type: application/json at most cases.

To provide the custom MIME type with convention, we don’t need to guess the resource type from the fields of the JSON nor the request URL. Also it provides a way to control the versioning based on resources.

JSON definition collision issues

It also gives us a way to distinguish the type for the same entity type designed by different teams in the company.

application/vnd.vvtk.application1.user.v1+json
application/vnd.vvtk.application2.user.v1+json

The design purpose of such a long name: different team in the company is expected to design different object schema for the same resource type; so it would be a problem to understand application/vnd.vendor.user+json if more than one API returns this media type. If you have strong confidence it would not conflict, you MAY be able to provide application/vnd.vendor.user+json and drive all other teams in the company to follow(or avoid) this mime type.

Notice: RFC requires us to register vendor to IANA but we don’t register yet. It’s not a good practice to provide custom vendor with x- prefix.

The design of convention somewhat being aligned to URN convention. Consider to modify them both at the same time if necessary.

MIME type versioning with URL versioning

It seems to be a collision with URL versioning, but there’s use case we could do it both to provide wider flexibility.

• MAY use them both or use only one of them to versioning the resource.
• SHOULD follow the same versioning strategy if only take one of them.

Content negotiation about versioning

The client specify common json format

Accept: application/json

• SHOULD return custom json MIME type if designed

200 OK
Content-Type: application/vnd.vvtk.alive-app.user.v2+json

The client does not specify versioning

Accept: application/vnd.vvtk.alive-app.user+json

• SHOULD return latest version of the resource

Content-Type: application/vnd.vvtk.alive-app.user.v3+json

The client specify the versioning

Accept: application/vnd.vvtk.alive-app+v1.user+json

• SHOULD return the expected resource with the specified versioning if supported

200 OK
Content-Type: application/vnd.vvtk.alive-app+v1.user+json

• SHOULD return 406 Not Acceptable if the specified versioning does not exist

406 Not Acceptable

Reference

• https://datatracker.ietf.org/doc/html/rfc6838

Design References

• https://developers.whispir.com/1f256b49f0100-using-json-and-xml-headers