05 - Patterns to Implement & Avoid

05 - Patterns to Implement & Avoid

When you're building your API, you should avoid falling into the following traps:

Patterns to Avoid

Warning
These are patterns that you should avoid.

Avoid Non-JSON Requests/Responses

Your API should only accept JSON requests and only respond with JSON responses.  Do not utilize multi-part form data or other methods.

Avoid Inconsistent JSON Requests/Responses

You JSON should always look the same every single time.

Avoid URL Path Parameters and URL Query Parameters

URL and Query parameters are brittle and subject to inconsistent encoding schemes.  You should avoid them.  Only receive data from the JSON body and only respond through the JSON response.  The only time it is acceptable the single "id" path parameter with the UPDATE and DELETE operations.

Avoid Case-Sensitive JSON

When possible, your JSON should be case in-sensitive.  For example, setting firstname, firstName, or FirstName should all be valid.

Avoid Linking Items by Name

APIs are designed for computers to use, not people.  Whenever an object is related to another object, always return IDs and not names.
For example, with a person, do not return company_name, instead, return company_id.  On matters, don't return practicearea_name, but instead return practicearea_id.

Avoid Geo-Centric Dates

Your API should avoid dates such as "2022-02-25 10:59:31".  A date like this does not contain a timezone which is ambiguous: it is in the user's time zone, the server's timezone, GMT, or some other timezone?  Instead, use ISO8601 DateTimeOffsets.  For example: 2017-04-19T11:18:51-07:00

    • Related Articles

    • Push Connector Requirements.

      Universal Migrator facilitates migrations between hundreds of different applications into destination applications whom we have built a push connector for. If you are reading this article, you likely want Universal Migrator to load data into your ...

    • How to Extract an Icon Image from an EXE File

      This guide will walk you through extracting icon images from an executable (EXE) file using 7-Zip. This method allows you to access icon resources within EXE files and save them as .ico files. Requirements 7-Zip: Ensure 7-Zip is installed on your ...

    • 4.3 - Migration Philosophy: Financial Migrations

      When transferring financial information between different systems, it is important to understand the philosophy behind how the Universal Migrator thinks about financial data and how those conclusions were reached. All Math is Not Created Equal Each ...