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