WHAT IS A RESTful API?

REST is an acronym for REpresentational State Transfer. It is an architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his famous dissertation.  A RESTful API is an API that is implemented over local-area and wide-area networks (Intranet/Internet), most commonly via HTTP (Web Browsers).

An API (Application Programming Interface) is a “contract” or “set of rules” between two applications that exchange information. It allows developers to write software and/or web applications that can access and utilize the resources and services of these different applications.

REST RESOURCES AND ROUTES:

There are two core parts of a REST API: one is RESOURCES (which you could call Entities, or Objects) and you act on those resources via standard HTTP requests with standard HTTP Verbs. To understand resources, you must understand that REST APIs are organized around URIs — uniform resource identifiers — (web urls) and that generally those are centered around these objects.

GoldMine Objects: Primary Contacts, Additional Contacts, Custom Fields, Emails, Details, Notes, Calendar, History, etc.

REST VERBS (HTTP REQUEST METHODS):

GET, POST, PUT, PATCH, DELETE

While there are technically 9 HTTP request methods (what I’m calling verbs) I’ve only ever seen five implemented to perform actions with a REST API. This is basically because REST methods map pretty well to “CRUD.” CRUD is a common acronym which stands for Create, Read, Update, Delete — the four operations that one wants to do with a piece of data. Four operations don’t need 9 request types.

In any case, the five HTTP methods used with most REST APIs are:

  • GET which is used for reading data. GET requests — inside and outside of REST contexts — are considered “read only.”
  • POST which is generally used for creating new data. Sometimes POST is used for updating too, but generally “best practice” says to use…
  • PUT or PATCH for updating data. Why two? Because sometimes you want to replace it completely — when you PUT — and sometimes you just want to replace or change a value of two — when you PATCHUpdate operations are kind of the least standardized in practice, because support for PUT and PATCH isn’t as universal as GETPOST, and DELETE.
  • DELETE is for deleting data. Hardly seems worth a sentence of explanation.

EXAMPLE REST API URI’S:

HTTP GET    https://api.example.com/contact1/{id} (get contact with a specific id)
HTTP POST   https://api.example.com/contact1/  (create a contact using the posted JSON data)
HTTP GET    https://api.example.com/contact1/primaryemail/{id} (get the primary email address of the contact with a specific id)
HTTP DELETE https://api.example.com/contact/{id} (delete contact with specific id)

CRUD Operations in SQL Server

GoldMine’s data is stored in a SQL Server Database, and SQL is the language used to interact with that database.

CRUD is an acronym that stands for Create, Read, Update, and Delete.
These are the four most basic operations that can be performed with most traditional database systems and they are the backbone for interacting with any database.

SQL uses the following commands for interacting with and performing CRUD operations against the SQL Database.

SELECT, INSERT, CREATE, UPDATE, DELETE

EXAMPLE SQL QUERIES:

SELECT Contact, Company, Address1, Address2, City, State, Zip
FROM  CONTACT1
WHERE RECID = “BD32345234234”

DELETE
FROM CONTACT1
WHERE RECID = “BD32345234234”

INSERT INTO CONTACT1
(CONTACT, COMPANY,ADDRESS1, ADDRESS2, CITY, STATE, ZIP)
VALUES
(“JOHN DOE”, “ABC INC”,”123 Acme Way” , “Suite 23″ ,”Disney”, “FL”, “34233”)

UPDATE CONTACT1
SET CONTACT = “John Doe”, COMPANY = “ABC Inc”, ADDRESS1 = “123 Acme Way”, ADDRESS2 = “Suite 23”, CITY = “Orlando”, STATE = “FL”, ZIP = “34234”
WHERE RECID  = “BD32345234234”

WHAT IS JSON?

The REST architecture allows API providers to deliver data between their applications in multiple formats such as plain text, HTML, XML, YAML, and JSON

JavaScript Object Notation is a syntax for storing and exchanging data.
JSON is text, written with JavaScript Object Notation.

Basic Example:
var JSON = ‘{“Firstname”:”John”, “Lastname”:”Doe”, “Age”:31, “City”:”New York”}‘;
var CONTACT = JSON;

Most RESTful API’s use JSON as their preferred data format for exchanging data.

Data is exchanged between the Client (Web Browser) and Server (REST API) using HTTP Methods (GET, POST, PUT, DELETE) which instructs the API what to do with the data being sent to it.
The API designer/provider defines the RULES for how to utilize the data to interact with the database and what Methods will be used with the API URL End Points. The API will send JSON data back to the Client.

WEBHOOKS:

Webhooks are a way that Web Apps can send automated messages or information to other apps. It’s how PayPal tells your accounting app when your clients pay you, it’s how Twilio routes phone calls to your number, and how WooCommerce can notify you about new online orders in your Slack.  They’re a simple way your online accounts can “speak” to each other and get notified automatically when something new happens. In many cases, you’ll need to know how to use Webhooks if you want to automatically push data from one App to another. Webhooks utilize unique URL end points (web addresses) for automated workflows. Webhooks consist of a TRIGGERING APP that sends/posts data to a URL IN ANOTHER APP and that APP will be configured to do something useful with that data.

Example Webhook:

Mailchimp Unsubscribe Webhook:

When someone unsubscribes from a Mailchimp Campaign, Mailchimp will automatically send that subscribers data to my URL End Point (web address) so that I can do something with that users data in my Application or other applications. The subscribers data is usually sent to my url end point in a JSON format and I will need to process that data.

Web automation engines like Zapier, Microsoft Flow, IFTTT, Tray.io, Integromat, Automate.io, Workato, Zoho Flow and many others provide the ability to integrate a wide variety of systems via web hooks. These web service providers have written integrations between thousands of different apps using the API’s of those Apps. These systems allow a non-developer to easily, quickly and affordably integrate the different Web Apps they may use.

GoldMine RESTful API Examples:

A. Web Based GoldMine CRM – (Access your GoldMine Data via a Web Browser)
B. Mailchimp integration with GoldMine
C. Calendly integration with GoldMine
D. GoldMine integration with Twilio (SMS Text Messages)
E. Hardbounce Email Management App
F. Zip Code Database Management App
G. Mapping/GEO Code Management App

Whats required/involved with hosting/using the GoldMine RESTful API?

  1. A Domain name for accessing the GoldMine REST API. ie www.myrestapi.com
  2. An SSL Certificate (Lets Encrypt) https://www.sslforfree.com/ or one purchased from a CSA.
  3. A Web Server (IIS or WAMP) installed on a Computer or Server on the network where your GoldMine SQL Database is hosted.
  4. Ports 80 and 443 opened on the Firewall and Port Forwarding Setup on the Router
  5. Once the API is installed and setup/configured you can now start using it to integrate your GoldMine with the many different web applications that are available today. First Direct Corp. will work with you to setup these integrations and advise you on what is and isn’t possible or feasible. You could even hire or contract any Web Developer who has experience with using RESTful APIs and/or the application you want to integrate with.

Pricing will be made available on a per request basis as each persons requests will be different
and unique to what they want/need as far as integration. Please contact First Direct Corp. if you are interested in learning more.