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

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

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

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

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

    • Creating/Viewing a Fiddler Capture

      When using Universal Migrator to inject data into a destination system, it is possible that you may run into a bug in either Universal Migrator or in the API you are injecting into. If you get API errors and the data seems correct, please sent us a ...