Velma Rest API

Introduction
Authentication
Requests
Sample Calls
HTTP Verbs
Responses
HTTP Status Codes
Errors
Rate Limiting
Filtering
Sorting
Fields
Extended Fields

Try the Velma API

Introduction

Hi an welcome to the Velma Rest API. We have created this with the goal of allowing our integrators, partners and subscribers a way to control the retrieval and submission of data that better suits their needs.

We have really tried to provide a well defined comprehenisve API. All feedback is welcome, please send to api.velma.com

Authentication

The API will be using OAuth2.

OAuth2 Code Example Here

Requests

Velma's base API url is https://api.velma.com/api/route Please replace route with the call you are making. 

https://api.velma.com/api/contacts?orderBy=lastname

Sample Calls

Please click on the view calls list link. Select the call you are interested in and a variety of samples will be provided in the calls documentation.

HTTP Verbs

We are using standard HTTP Verbs

  • GET - To retrieve a resource or a collection of resources
  • POST - To create a resource
  • PATCH - To modify a resource
  • PUT - To set a resource
  • DELETE - To delete a resource

Responses

Please click on the view calls list link. Select the call you are interested in and an example of the responses will be available for your review.

HTTP Status Codes

Successs:

  • 200 OK - Call was a success

Error:

  • 400 bad_request - Something is wrong with the request
  • 415 Incorrect Media Type - The media type is not valid for the call
  • 401 unauthorized - Authentication credentials have failed
  • 403 forbidden - The user does not have access to the request
  • 500 internal_server_error
  • 429 Too Many Requests - Exceeded rate limits

Errors

Errors will be provided in the return call.

You will receive an object with a message stating exactly what is wrong.

Message: "No property 'lastName1' exists in type 'Contact'"

Rate Limiting

Documention Coming Soon

Code Here

Getting Data

All data fetching will utilize properties of the objects inside the data array. If you see an object referenced then you can use it to filter, sort, include etc. We will go over the individual methods below.

  • Data:
  • [
  • {
  • "FirstName": "Rod",
  • "LastName": "Laver",
  • "WorkPhone": "555-3456",/li>
  • "OtherPhone": "555-4567",
  • "ReferredBy": "LaverRod",
  • "PreferredCommunication": "Email",
  • "DateOfBirth": "2015-08-24T14:22:46.1391601-06:00"
  • }
  • ]

Filtering

You can filter the data using the following operators.

  • eq - equal to
  • != - not equal to
  • gt - greater than
  • lt - less than
  • ge - greater than or equal to
  • le - less than or equal to
  • startswith - starts with
  • endswith - ends with
  • contains - contains

Examples:

  1. Get contacts where lastname=djokovic 

    https://api.velma.com/api/contacts?filterBy=lastname&filteroper=eq&filterval=djokovic

  2. Get contacts where ranking > 1 

    https://api.velma.com/api/contacts?filterBy=ranking&filteroper=gt&filterval=1

  3. Get contacts where ranking > 1 *and* lastName startsWith 'c' 

    https://api.velma.com/api/contacts?filterString=ranking,gt,1;lastName,startswith,c

Sorting

  1. Get contacts sorted by firstname 

    https://api.velma.com/api/contacts?orderby=firstname

  2. Get contact 1 loans sorted by ranking 

    https://api.velma.com/api/contacts/1/loans?orderby=ranking

  3. Get contact 1 loans sorted by ranking descending (-ranking) , uses the '-' 

    https://api.velma.com/api/contacts/1/loans?orderby=-ranking

  4. Get contacts sorted by ranking descending (-ranking) then lastName acending (lastname) 

    https://api.velma.com/api/contacts/1/loans?orderBy=-ranking,lastname

Fields

The api provides a way to only select the fields you want from the collection of targeted objects. Utilize the properties separated by commas to ask for specific fields.

  1. Get contacts but only give me firstname,lastname and ranking 

    https://api.velma.com/api/contacts?fields=lastname,firstname,ranking

Extended Fields

Extending fields are for users with higher roles (Eg: Corp Admins) that, if they know about them can request non-public fields. Note: If these are mixed with the fields query parameter you can request a couple public fields with one special field. If not mixed then the entire object plus your special field will be requested.

  1. Get contacts but add a requested special field. additional field (let's call this one 'special') 

    https://api.velma.com/api/contacts?extfields=special

  2. Get contacts but only give me firstname,lastname and one requested special field. 

    https://api.velma.com/api/contacts?fields=firstname,lastname&extfields=special

Pagination

Query Parameter(s): pageCount and page

The pagination query allows users of the Velma Rest API to build paged lists.

  1. Give me page2 of the contacts with only 10 per page. So this would be contact 11 - 20 

    https://api.velma.com/api/contacts?pageCount=10&page=2fields=lastname,firstname,ranking