Advanced API Formats

Beyond simple HTTP REST APIs, there are several advanced API formats and protocols that offer unique capabilities and benefits for specific integration scenarios.

SOAP (Simple Object Access Protocol)

SOAP is an XML-based messaging protocol for exchanging structured information in web services:

Key Characteristics

XML-based: Uses XML for message formatting
Protocol independent: Works over HTTP, SMTP, TCP, etc.
Strongly typed: Defined through WSDL (Web Services Description Language)
Enterprise focused: Common in older enterprise systems
Built-in standards: Includes WS-Security, WS-Addressing, etc.

FileMaker Integration

FileMaker can integrate with SOAP services through:

# SOAP request using Insert From URL
Set Variable [$soapEnvelope; Value: "<?xml version=\"1.0\" encoding=\"utf-8\"?>
<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">
  <soap:Body>
    <GetStockPrice xmlns=\"http://example.com/stock\">
      <StockName>IBM</StockName>
    </GetStockPrice>
  </soap:Body>
</soap:Envelope>"]

Set Variable [$options; Value: "-X POST -H \"Content-Type: text/xml; charset=utf-8\" -H \"SOAPAction: http://example.com/GetStockPrice\" --data " & Quote($soapEnvelope)]

Insert From URL [Select; $result; "https://example.com/stockquote"; cURL options: $options]

When to Use SOAP

Integrating with legacy enterprise systems
When WSDL-defined interfaces are required
For systems requiring WS-Security standards
When a formal contract is needed between systems

GraphQL

GraphQL is a query language for APIs that gives clients the power to request exactly the data they need:

Key Characteristics

Client-specified queries: Clients define the exact data shape they need
Single endpoint: One endpoint handles all data requests
Strongly typed: Schema defines available types and operations
Hierarchical: Mirrors the way data is used, not stored
Introspective: API can be queried for its own schema

FileMaker Integration

Integrating with GraphQL from FileMaker:

# GraphQL query using Insert From URL
Set Variable [$query; Value: "{
  user(id: \"123\") {
    name
    email
    orders {
      id
      status
      items {
        productName
        quantity
      }
    }
  }
}"]

Set Variable [$options; Value: "-X POST -H \"Content-Type: application/json\" --data '{\"query\": " & JSONString($query) & "}'"]

Insert From URL [Select; $result; "https://api.example.com/graphql"; cURL options: $options]

When to Use GraphQL

When clients need to request varying data shapes
To reduce multiple round-trips to the server
For apps with complex data relationships
When API evolution needs to happen without versioning

gRPC (Google Remote Procedure Call)

gRPC is a high-performance RPC framework that uses HTTP/2 for transport and Protocol Buffers for serialization:

Key Characteristics

Binary protocol: More efficient than text-based protocols
Strong typing: Interface defined with Protocol Buffers
Code generation: Automatic client/server code generation
Bi-directional streaming: Supports streaming in both directions
HTTP/2: Leverages HTTP/2 features like multiplexing

FileMaker Integration

Direct gRPC integration with FileMaker is challenging. Common approaches include:

Create a REST proxy: Build a service that exposes gRPC services via REST
Use plugins: Some plugins may support binary protocols
Middleware: Create middleware that FileMaker can communicate with, which in turn uses gRPC

When to Use gRPC

For high-performance, low-latency services
Microservices communication within an organization
When bandwidth efficiency is critical
Services requiring streaming capabilities

EDI (Electronic Data Interchange)

EDI is a standardized format for exchanging business documents between organizations:

Key Characteristics

Standardized formats: X12, EDIFACT, etc.
Business document focus: Invoices, purchase orders, etc.
Widespread in industries: Retail, healthcare, logistics, manufacturing
Strict validation: Follows specific format standards
Integration-focused: Designed for B2B integrations

FileMaker Integration

FileMaker can work with EDI through:

Translation services: Use third-party services to convert between EDI and easier formats (XML, JSON)
Direct parsing: For simple EDI documents, FileMaker can parse text
Plugins: Some plugins offer EDI parsing capabilities

Example of a simple EDI parser in FileMaker:

# Very basic X12 810 (Invoice) segment parser
Set Variable [$ediText; Value: "ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *210701*1230*U*00401*000000001*0*P*>~GS*IN*SENDER*RECEIVER*20210701*1230*1*X*004010~ST*810*0001~BIG*20210701*INV123**20210630~N1*ST*ACME CORP~N3*123 MAIN ST~N4*ANYTOWN*NY*12345~ITD*01*3*2*10*30**60~IT1*1*12*EA*9.99**BP*1234567890123~IT1*2*10*EA*29.99**BP*2345678901234~TDS*32868~CTT*2~SE*11*0001~GE*1*1~IEA*1*000000001~"]
Set Variable [$segments; Value: Substitute($ediText; "~"; "¶")]

# Extract header info
Set Variable [$isaSegment; Value: GetValue($segments; 1)]
Set Variable [$sender; Value: Middle($isaSegment; Position($isaSegment; "*"; 1; 7) + 1; 15)]
Set Variable [$receiver; Value: Middle($isaSegment; Position($isaSegment; "*"; 1; 9) + 1; 15)]

# Extract invoice info
Set Variable [$bigSegment; Value: FilterValues($segments; "BIG*")]
Set Variable [$invoiceDate; Value: Middle($bigSegment; Position($bigSegment; "*"; 1; 1) + 1; Position($bigSegment; "*"; 1; 2) - Position($bigSegment; "*"; 1; 1) - 1)]
Set Variable [$invoiceNumber; Value: Middle($bigSegment; Position($bigSegment; "*"; 1; 2) + 1; Position($bigSegment; "*"; 1; 3) - Position($bigSegment; "*"; 1; 2) - 1)]

# Process line items
Set Variable [$lineItems; Value: FilterValues($segments; "IT1*")]
# Further processing would extract data from these lines

When to Use EDI

B2B integration with large retailers or suppliers
Healthcare claim processing
Logistics and supply chain integration
Financial transaction processing

OData (Open Data Protocol)

OData is an OASIS standard protocol for creating and consuming queryable and interoperable REST APIs:

Key Characteristics

Standardized querying: Common syntax for filtering, sorting, etc.
Metadata aware: Services describe their data model
Entity relationships: Supports navigation between related entities
Batch processing: Multiple operations in a single request
Standard operations: CRUD operations with standard semantics

FileMaker Integration

FileMaker can consume OData services through the standard REST interface:

# OData query using Insert From URL
# Get customers filtered by city and ordered by name
Set Variable [$url; Value: "https://services.odata.org/V4/Northwind/Northwind.svc/Customers?$filter=City eq 'London'&$orderby=CompanyName&$select=CustomerID,CompanyName,ContactName&$format=json"]

Insert From URL [Select; $result; $url]

# Process JSON result
Set Variable [$customers; Value: JSONGetElement($result; "value")]
# Work with customer data

When to Use OData

When standardized query capabilities are needed
For data-centric REST API design
When clients need flexible querying options
For systems requiring formal metadata description

Best Practices for Advanced APIs

Understand the protocol: Each protocol has specific strengths, weaknesses, and patterns
Use appropriate tools: Consider middleware or plugins for complex protocols
Security considerations: Each protocol has different security models and requirements
Performance testing: Test with representative data volumes and patterns
Error handling: Implement protocol-specific error handling
Versioning strategy: Plan for API evolution and changes
Documentation: Maintain clear documentation of integration points

Advanced API Formats

On this page