Contract-Based Web-Services API Deep DiveGabriel Michaud

Goals of this Session

1. Tell you more about the new web services technology available in 5.3 and why you should use it

2. Show you how to use the contract-based web services in your projects, new and existing

3. Give you a glimpse at upcoming enhancements

Why build a new web services API?

Reason 1: Tight Coupling with UI

What if the Terms label was renamed to “Payment Terms” ?

Reason 2: Ease of use

• The design of “classic” web-services is highly influenced by integration services and the screen command/actions model.

• Intuitiveness is not one of the strong points of this model• Everything is a string• Multi-dimensional arrays• Some operations happen ”magically” (searches)• Wizardry and black magic is needed (commit flag)

• Complexity of use doesn’t increase linearly with the complexity of usage scenarios• Scenarios which seem basic like changing a customer code, adding a payment method end up

requiring knowledge of screen internals

• A lot of code is needed for very simple operations

Retrieving a stock item with the “classic” API

Retrieving a stock item with the new API

Reason 3: Future proofing

Working with the contract-based web services API

Viewing and configuring endpoints

• Endpoints form the contract between Acumatica and the consumer of the API

• Key concepts• Interfaces and versions• Top Level, Linked and Detail Objects• Mappings• Actions (and default action)• Endpoint Service• Maintenance Service

• A default endpoint encompassing the most common scenarios is included; this service will be maintainted by Acumatica

Web Service Endpoints

Let’s write some code!

• Retrieving data• GetList (retrieveFullEntities, ****Value types)• Get• Filtering• Custom fields

• Creating/updating a record (Put)

• Deleting data

• Invoking actions (ex: Release)• Long-running process status

Advanced topics

• Working with files

• Smart panels• Mapped via adapters (App_Code\Entity)• Adapters abstract custom/non-standard logic that would be otherwise• Existing examples: Shipment Detail, PO Receipt

• Dialogs• In an action has a confirmation dialog, in most cases it will be

confirmed automatically without an adaptor

Packaging and publishing your own endpoints

• Using API to import schema via maintenance service• Exporting to XML• GetSchema/PutSchema

• Packaging schema via customization manager

Migration Strategy

• The classic web services API is not going anywhere and will remain supported

• New ISV integrations should be built on the new contract-based web services API – sometimes next year it will become mandatory for solution certification

• Existing code can be migrated gradually; you can mix both technologies in the same product (share session cookies to avoid needing multiple logins)

• The existing web services API not going anywhere and will remain supported

Looking Ahead

Endpoint Extensibility

• Benefits of extensibility

• Extensibility scenarios• Add new fields• Add new screens

• What to do until extensibility is available• You should NOT modify the predefined endpoint shipping with the app• Ask us to add field• Copy paste endpoint definition -> but you’ll have to maintain the whole thing• If custom field – use CustomFields collection• For your own screens – you can create a separate endpoint for now

REST• Comparison of SOAP and REST

  SOAP REST1 XML-based message protocol over HTTP Simply HTTP2 All of the data is contained in the message itself Data is spread out over different parts of HTTP protocol 3 One URL (endpoint), resource being affected is defined by

message and SOAP ActionDifferent URLs for different resources (ideally, every resource is reachable by unique and non-changing URL)

4 Always POST, actual call semantics are defined by SOAP Action

Call semantics are defined by HTTP method (GET/PUT/POST/DELETE)

5 Return status code is always 200 OK, actual success/failure/other semantics are expressed in message

Basic (common) semantics are expressed in HTTP status code and HTTP headers

6 Request/response format is XML Request/response format is negotiable (usually JSON and XML)7 Standard-defined schema definition (WSDL and XSD) No standard schema definition8 Hard to call from browser-based JavaScript (have to

implement XML/SOAP parser)Easy to call from browser-based JavaScript (JSON parser is built-in) and “newer” languages like Ruby on Rails

9 Hard to introduce caching Can rely on HTTP-defined standards for caching

Wrap-Up

• Thank you to early adopters – Kensium (PC Bennett) and OzDevelopment (Descartes)

• Training Materials now available on Acumatica University

• I210 Contract-Based Web Services 5.3

• Questions?

THANK YOUGabriel Michaud | gmichaud@acumatica.com

No Reliance This document is subject to change without notice. Acumatica cannot guarantee completion of any future products or program features/enhancements described in this document, and no reliance should be placed on their availability.

Confidentiality: This document, including any files contained herein, is confidential information of Acumatica and should not be disclosed to third parties.

No Reliance This document is subject to change without notice. Acumatica cannot guarantee completion of any future products or program features/enhancements described in this document, and no reliance should be placed on their availability.

Confidentiality: This document, including any files contained herein, is confidential information of Acumatica and should not be disclosed to third parties.