# Overview

# What is an API?

API, or Application Programming Interface, defines the relationship between two pieces of software. It is a regulated request sent from one with a response sent from the other. Many systems provide an API so that external plugins can take advantage of the data and processing power available.

overview-workflow

# What is REST?

The way we use APIs are through something called REST or Representational State Transfer. The client software sends all necessary information with each request. REST APIs utilize a standard protocol, typically HTTP which is stateless. Statelessness means no dependencies for requests. This means no dependencies and that is super scalable.

overview-crud

The reason we use REST is for with a server to retrieve and modify information. HTTP and JSON are the standard for this type of operations. HTTP is the protocol of the web and JSON is, for the most part, machine and human readable. REST services typically provide the basic "CRUD" operations; create, read, update, delete. In this way, proprietary algorithms can integrate with Petro.ai, modify jobs and custom variables, and export/Import data to/from any system (Python, R, SQL, etc.).

{
    "pwi":"5cab2abd32435bedcab",
    "wellid":"TOM HANKS 001H",
    "basinName":"Permian",
    "countyName":"Harris"
}

# Petro.ai CRUD Operations

The Petro.ai API utilizes the same command structure as popular APIs.

overview-endpoints

Command Description
HTTP POST Create new records
HTTP GET Read new record
HTTP PUT Update/Replace records
HTTP PATCH Update/Modify portions of records
HTTP DELETE Deletes records

# Parameters

Each endpoint has parameters which define allowed values for a request. HTTP GET uses query parameters e.g. /api/UnitsDefinitions?Names=MyVar. All other HTTP methods use json body which is send via header.

# Models

Every API request and response is mapped to a model. All document models can be seen in API documents. This is useful for seeing field types and structure of nested docs

TIP

API Doc Models do not show default values (e.g. isDeleted ≠ true)