Understanding APIs

Created by Reachware Support, Modified on Sat, 7 Mar at 2:45 PM by Reachware Support

API (Application Programming Interface): is a set of rules and protocols that allow two software systems to communicate with each other using requests and responses.

In Reachware Studio, APIs are the foundation of every integration. They allow your flows to connect with external systems such as CRMs, e-commerce platforms, ERPs, databases, and cloud services.

An API acts as a contract between two systems. It defines:

What actions can be performed (create, read, update, delete)
How those actions should be requested
What data format must be used
What type of response will be returned

How APIs Work

API communication follows a client-server model:

Client: The system that sends the request
Server: The system that processes the request and sends a response

Example: Shopify to Salesforce Integration

Your integration sends a request to Shopify's API asking for customer data.

Shopify processes the request and retrieves the information.

Shopify returns the data in a structured format (usually JSON).

Your integration sends that data to Salesforce's API.

Salesforce creates or updates the customer record.

Each request is processed independently, especially in REST APIs (stateless communication).

Types of APIs

1. REST APIs (Most Common)

REST (Representational State Transfer) is the most widely used API architecture.

Uses standard HTTP methods (GET, POST, PUT, DELETE)
Works with URLs called endpoints
Typically exchanges data in JSON format
Stateless — each request contains all necessary information

GET https://api.shopify.com/customers/12345

2. SOAP APIs (Legacy Systems)

SOAP (Simple Object Access Protocol) is an older protocol.

Uses XML format
Requires strict contracts (WSDL)
More rigid structure
Often used in enterprise systems

3. GraphQL APIs (Flexible Queries)

GraphQL is a query language designed for APIs.

Clients request exactly the data they need
Single endpoint for all operations
Reduces over-fetching and under-fetching

4. Webhooks (Event-Driven)

Webhooks work alongside APIs.

Data is pushed automatically when events occur
No need for repeated polling
You provide a URL to receive event data

Key API Concepts

Endpoints

An endpoint is a specific URL where an API resource is accessed.

https://api.example.com/customers    → List all customers
https://api.example.com/customers/123 → Get a specific customer
https://api.example.com/orders      → List all orders

HTTP Methods

Method	Purpose	Example
GET	Retrieve data	Get list of customers
POST	Create data	Create new order
PUT / PATCH	Update data	Update customer address
DELETE	Remove data	Delete product

Authentication

APIs verify who is making the request. Reachware Studio supports the following authentication methods:

1. API Keys — A simple token included in the request.

X-API-Key: abc123xyz

2. OAuth 2.0 — More secure method using temporary access tokens. Common with Google, Microsoft, and Salesforce. Reachware Studio manages the OAuth flow automatically.

3. Bearer Tokens — Token included in the request header.

Authorization: Bearer eyJhbGc...

Request and Response Structure

Sample API Request

POST https://api.example.com/customers
Content-Type: application/json
Authorization: Bearer abc123

{
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com"
}

Sample API Response

{
"id": "cust_12345",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"createdAt": "2026-02-09T10:30:00Z",
"status": "active"
}

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid data
401	Unauthorized	Authentication failed
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Issue on server side

Rate Limiting

APIs limit how many requests can be made within a time period to protect system performance.

Example: Salesforce allows a limited number of API calls per 24 hours.

Data Formats

JSON (Most Common in REST)

{
"orderId": "12345",
"customer": {
"name": "Jane Smith",
"email": "jane@example.com"
},
"items": [
{ "productId": "ABC", "quantity": 2, "price": 29.99 }
]
}

XML (Common in SOAP)

<order>
<orderId>12345</orderId>
<customer>
<name>Jane Smith</name>
<email>jane@example.com</email>
</customer>
</order>

API Best Practices in Reachware Studio

Handle Errors Properly

Always check status codes
Implement retry logic for temporary failures
Log errors for troubleshooting

Respect Rate Limits

Avoid unnecessary calls
Use pagination for large datasets
Implement throttling when required

Test Before Production

Use sandbox environments
Validate request formats
Test edge cases and failure scenarios

Monitor Integrations

Set alerts for failures
Review logs regularly