An overview of the new web services API included in Acumatica 5.3.

1. Contract-Based Web-Services
API Deep Dive
Gabriel Michaud

2. 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

3. Why build a new
web services API?

4. Reason 1: Tight Coupling with UI
What if the Terms label was
renamed to “Payment Terms” ?

6. 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

7. Retrieving a stock item with the “classic” API

8. Retrieving a stock item with the new API

9. Reason 3: Future proofing

10. Working with the
contract-based
web services API

11. 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

12. Web Service Endpoints

13. 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

14. Advanced topics
• Working with files
• Smart panels
• Mapped via adapters (App_CodeEntity)
• 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

15. Packaging and publishing your own endpoints
• Using API to import schema via maintenance service
• Exporting to XML
• GetSchema/PutSchema
• Packaging schema via customization manager

16. 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

17. Looking Ahead

18. 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

19. REST
• Comparison of SOAP and REST
SOAP REST
1 XML-based message protocol over HTTP Simply HTTP
2 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 Action
Different 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 definition
8 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

20. 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?

21. THANK YOU
Gabriel Michaud | gmichaud@acumatica.com

22. 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.