Which P21 API Should I Use?¶

P21 exposes five distinct API families. Each is designed for a different class of problem. Choosing the wrong API leads to unnecessary complexity, poor performance, or missing business logic enforcement. This guide helps you make the right choice.

Quick Decision Matrix¶

Start here. Find your primary need in the left column, then use the recommended API.

API Abstraction Layers¶

The five API families are not peers — they operate at different abstraction levels. Understanding this hierarchy explains why some APIs are "heavier" than others.

flowchart TD
    App["**Your Application**"]

    subgraph ui["UI-Based APIs — require an active session"]
        CS["Common Services\nSession management"]
        IA["Interactive API\nWindow automation"]
        TA["Transaction API\nBusiness services"]
    end

    subgraph rest["REST APIs — Bearer token auth"]
        EA["Entity API\nREST CRUD"]
        DS["Data Services\nOData queries"]
    end

    App --> CS
    App --> IA
    App --> TA
    App --> EA
    App --> DS
    CS -->|"provides session for"| IA
    CS -->|"provides session for"| TA

Detailed API Descriptions¶

Entity API¶

Base URL: https://{server}/api/entity/ Auth: Bearer Token Format: XML

The Entity API is a RESTful interface that maps directly onto P21 business entities — Customer, Order, Vendor, Item, etc. It supports standard HTTP verbs (GET, POST, PUT, DELETE, PATCH) and is the most straightforward API to integrate with.

Strengths:

• Simple, predictable URL patterns (/entity/Customer, /entity/SalesOrder)
• Stateless — no session to manage
• Fast for single-record reads and writes
• Easy to map to standard integration patterns (REST webhooks, ETL connectors)

Limitations:

• XML-only format (no JSON)
• Does not fire P21 business rules or window events — you are writing directly to the data layer
• Requires knowing the exact entity schema

Best for:

• Point-to-point integrations where you control the data quality
• Systems that need to create/update records in bulk without business rule overhead
• Reading individual records by key

GET  https://{server}/api/entity/Customer?customer_id=C0001
POST https://{server}/api/entity/SalesOrder
PUT  https://{server}/api/entity/Customer?customer_id=C0001

Data Services API¶

Base URL: https://{server}/api/dataservices/ Auth: Bearer Token Format: JSON (OData v4)

The Data Services API exposes P21 data through OData v4 — the standard protocol for querying business data with rich filtering, sorting, and projection capabilities. Data is exposed through named views (e.g., p21_view_customer, p21_view_oe_hdr).

Strengths:

• Powerful OData query language ($filter, $select, $orderby, $top, $skip)
• JSON responses — easy to consume in JavaScript, Python, and modern tooling
• Excellent for read-heavy workloads: reporting, dashboards, data feeds
• Supports complex join-like queries through view design

Limitations:

• Primarily read-oriented — not designed for writes
• Query scope is limited to what is exposed as a view
• OData filter syntax has a learning curve

Best for:

• Reporting and analytics feeds
• Data export to external systems
• Building custom portals or dashboards on top of P21 data
• Any scenario needing filtered, paginated, sorted result sets

GET https://{server}/api/dataservices/p21_view_customer
    ?$filter=company_id eq '01'
    &$select=customer_id,customer_name,phone
    &$orderby=customer_name asc
    &$top=50

For full query examples, see the Data Services API reference.

Interactive API¶

Base URL: https://{server}/uiserver0/ui/interactive/v1/ Auth: Session (via Common Services) Format: XML/JSON

The Interactive API is P21's window automation interface. It allows you to open a P21 window (like the Sales Order Entry screen), populate fields, fire events, and save — exactly as a human user would. Every keystroke-level event fires, which means business rules run, calculated fields update, and validation logic executes.

Strengths:

• Most accurate representation of real P21 business behavior
• Business rules, Dynachange customizations, and all application logic fire
• Can handle complex multi-step workflows that involve multiple screens
• Results in P21 data that looks exactly like user-entered data

Limitations:

• Most complex API to work with
• Requires understanding of P21's window/control event model
• Session-based — requires session management overhead
• Slower than direct data APIs due to the overhead of window simulation

Best for:

• Replicating a complex human workflow in code
• Scenarios where business rules must fire (pricing logic, approval triggers, required field validation)
• Automating processes that a user currently performs manually
• Cases where the exact P21 window behavior is contractually or functionally required

Transaction API¶

Base URL: https://{server}/uiserver0/ui/interactive/transaction/ Auth: Session (via Common Services) Format: XML/JSON

The Transaction API is a service-oriented interface that exposes 500+ P21 business services as individual endpoints. Each service corresponds to a P21 business operation — creating an order, receiving a purchase order, processing a payment, etc. It is more structured than the Interactive API but more comprehensive than the Entity API.

Strengths:

• 500+ services covering the breadth of P21 functionality
• Service-oriented design is easier to document and test than window automation
• Executes business logic without requiring window simulation overhead
• Good coverage of complex multi-step operations

Limitations:

• Session-based — requires session management
• XML/JSON schema per service must be known in advance
• Less common community documentation than standard REST APIs

Best for:

• Full business transaction automation (end-to-end order entry, PO receiving)
• Scenarios where you need business logic to run but do not want to simulate windows
• High-volume transaction processing that needs to stay within P21's business layer

Common Services¶

Base URL: https://{server}/uiserver0/ui/common/v1/ Auth: Session Format: XML/JSON

Common Services is the session management and system information layer of P21. It is not a data access API — you use it to create and manage sessions, retrieve server information, manage user preferences, and query what services are available.

Strengths:

• Essential for any use of the UI-based APIs
• Provides server health and endpoint discovery
• Manages session state, preferences, and variables

Limitations:

• Not used for reading or writing business data
• Only relevant as infrastructure for other API calls

Best for:

• Session creation, keep-alive, and teardown
• Discovering available endpoints on a server
• Reading/writing session-scoped variables and preferences

For the complete endpoint reference, see Common Services API.

Multi-API Patterns¶

Real-world P21 integrations often combine multiple APIs. Here are common patterns:

Pattern: Bulk Import with Validation¶

1. Data Services API  →  Query existing records to detect duplicates
2. Entity API         →  Write new/updated records in bulk

Pattern: Order Entry Integration¶

1. Common Services    →  Create session
2. Data Services API  →  Validate customer and item existence
3. Interactive API    →  Drive Sales Order Entry window (rules fire)
4. Common Services    →  Close session

Pattern: Reporting Dashboard¶

Data Services API  →  All reads (customers, orders, inventory positions)
                       No session needed — stateless Bearer token calls

Pattern: Nightly Sync¶

1. Entity API  →  Pull changed records since last sync timestamp
2. Transform   →  Map to your external system's schema
3. Entity API  →  Write back any changes from the external system