contract-based web services api deep dive

22
Contract-Based Web-Services API Deep Dive Gabriel Michaud

Upload: gabriel-michaud

Post on 20-Mar-2017

659 views

Category:

Software


0 download

TRANSCRIPT

Page 1: Contract-Based Web Services API Deep Dive

Contract-Based Web-Services API Deep DiveGabriel Michaud

Page 2: Contract-Based Web Services API Deep Dive

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

Page 3: Contract-Based Web Services API Deep Dive

Why build a new web services API?

Page 4: Contract-Based Web Services API Deep Dive

Reason 1: Tight Coupling with UI

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

Page 5: Contract-Based Web Services API Deep Dive
Page 6: Contract-Based Web Services API Deep Dive

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

Page 7: Contract-Based Web Services API Deep Dive

Retrieving a stock item with the “classic” API

Page 8: Contract-Based Web Services API Deep Dive

Retrieving a stock item with the new API

Page 9: Contract-Based Web Services API Deep Dive

Reason 3: Future proofing

Page 10: Contract-Based Web Services API Deep Dive

Working with the contract-based web services API

Page 11: Contract-Based Web Services API Deep Dive

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

Page 12: Contract-Based Web Services API Deep Dive

Web Service Endpoints

Page 13: Contract-Based Web Services API Deep Dive

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

Page 14: Contract-Based Web Services API Deep Dive

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

Page 15: Contract-Based Web Services API Deep Dive

Packaging and publishing your own endpoints

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

• Packaging schema via customization manager

Page 16: Contract-Based Web Services API Deep Dive

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

Page 17: Contract-Based Web Services API Deep Dive

Looking Ahead

Page 18: Contract-Based Web Services API Deep Dive

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

Page 19: Contract-Based Web Services API Deep Dive

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

Page 20: Contract-Based Web Services API Deep Dive

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?

Page 21: Contract-Based Web Services API Deep Dive

THANK YOUGabriel Michaud | [email protected]

Page 22: Contract-Based Web Services API Deep Dive

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.