05 - Patterns to Implement & Avoid

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

Patterns to Avoid

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 ...

• Addendum: Building a Practice Management System

  If your organization is building a practice management system, the following guidance will help you build a future-proof application that will not need constant maintenance and refactoring as your client base grows. Database Design Use "long" Primary ...

• Attaching a VHD

  Open Computer Management Search for Computer Management in the Start Menu. Open Disk Management In the left panel, expand Storage and click on Disk Management. Attach the VHD In the menu bar, click Action → Attach VHD. Browse for the VHD or VHDX File ...

• Universal Migrator Data Security

  Why Universal Migrator is a Secure Choice for Data Migration In an era where data breaches and privacy concerns dominate headlines, especially in sensitive sectors like legal services, choosing the right tools for data migration is crucial. Universal ...

• 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 ...