03 - Required API Operations

03 - Required API Operations

Each data type that Universal Migrator will load to your system must support four operations:
  1. Create
  2. Search (list)
  3. Sparse Update
  4. Delete

All Four Operations are Required

Before our team can write the code to push a data type to your application, your API must support all four operations for that data type.

Required Operations

Create

This operation will be used to create new records in your system.  The invocation for Create should be something like this:

  2. POST /api/v1/contacts/create
  3. { 
  4.    “data”: { 
  5.      “type”: “person”, 
  6.      “first_name”: “John”, 
  7.      “last_name”: “Smith” 
  8.    } 
  9. } 

On success, it should return JSON bodies similar to this:

  2. { 
  3.    “data”: { 
  4.      “id”: “12345”, 
  5.      “type”: “person”, 
  6.      “first_name”: “John”, 
  7.      “last_name”: “Smith”, 
  8.      “created_at”: “2017-05-11T16:28:24-05:00”, 
  9.      “updated_at”: “2017-05-11T16:28:24-05:00”, 
  10.    }
  11. } 

On error, it should return JSON bodies similar to this:

  2. { 
  3.    “error”: { 
  4.      “type”: “validation_exception”, 
  5.      “message”: “something went wrong” 
  6.    } 
  7. } 


Search (List)

This operation will be used to find, filter, and/or page through records that have already been created.  The invocation for Search should be something like this:


  1. POST /api/v1/contacts/search
  2. { 
  3.    "filter": { 
  4.      "ids": [ "12345", "12346", "12347"], 
  5.      "type": "person", 
  6.      "created_after": "2017-05-11T16:28:24-05:00", 
  7.      "updated_after": "2017-05-11T16:28:24-05:00", 
  8.      "skip": 1000, 
  9.      "take": 50
  10.    } 
  11. } 

On success, it should return JSON bodies similar to this:

  2. { 
  3.    “data”: [
  4.       { 
  5.        “id”: “12345”, 
  6.        “type”: “person”, 
  7.        “first_name”: “John”, 
  8.        “last_name”: “Smith”, 
  9.        “created_at”: “2017-05-11T16:28:24-05:00”, 
  10.        “updated_at”: “2017-05-11T16:28:24-05:00”, 
  11.      },
  12.       { 
  13.        “id”: “12346”, 
  14.        “type”: “person”, 
  15.        “first_name”: “Jane”, 
  16.        “last_name”: “Doe”, 
  17.        “created_at”: “2017-05-11T16:28:24-05:00”, 
  18.        “updated_at”: “2017-05-11T16:28:24-05:00”, 
  19.      },
  20.     ]
  21. } 

On error, it should return JSON bodies similar to this:

  2. { 
  3.    “error”: { 
  4.      “type”: “validation_exception”, 
  5.      “message”: “something went wrong” 
  6.    } 
  7. } 


The Search API must support the following filters:
id_before
id_after

The Search API must support ordering items by Id.

Sparse Update

Info
A sparse update is an update API that only updates the provided fields and does not change any other fields.
 
This operation will be used to find records that have already been created.  The URL for Sparse Update should be something like this:

  2. PATCH /api/v1/contacts/12345
  3. { 
  4.    “data”: { 
  5.      “last_name”: “doe” 
  6.    } 
  7. } 

The responses should be identical to that of the Create operation.

Delete

This operation will be used to delete records that have already been created.  The URL for Delete should be something like this:

  2. DELETE /api/v1/contacts/12345
  3. { 

  5. } 

On success, it should return JSON bodies similar to this:

  2. { 
  3.    “status”: { 
  4.      “type”: “record_deleted”, 
  5.      “message”: “The record was successfully deleted”
  6.    }
  7. } 

On error, it should return JSON bodies similar to this:

  2. { 
  3.    “error”: { 
  4.      “type”: “validation_exception”, 
  5.      “message”: “something went wrong” 
  6.    } 
  7. } 


Other Requirements

Your API should have an endpoint which can identify the currently authenticated user.  Something like:
/api/v1/users/who_am_i

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

    • 01 - Allowing Universal Migrator to Authenticate with your API

      In order for Universal Migrator to push data to your system, you should select one of the authentication methods below. Option 1: OAuth2 Authentication (Recommended) If using this method, you should provision Universal Migrator as an OAUTH2 ...

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

    • Installing Unstoppable Copier

      Installing Roadkil’s Unstoppable Copier Roadkil’s Unstoppable Copier is a lightweight, free utility that allows you to recover files from disks with physical damage or read errors. It can also be used as a simple file backup tool, automating copy ...

    • 04 - Preserving Important Metadata

      Author/Editor information (along with created/modified timestamps) are very important to many law firms. When Universal Migrator pushes data to your API, it has the ability to push associated metadata if your API accepts it. We recommend that all ...