Am in a dialogue with a customer who wants to create a simple integration with another system and they asked about the different between the Agents and REST API. What is the difference and what shall be used when?
You probably already know, but for other readers who don't, we have three API options:
The SOAP API is normally accessed with client proxy wrappers. For this we provide proxies in the legacy SuperOffice.NetServer.Services nuget packages. Usage:
ContactAgent ca = new ContactAgent();
ContactEntity ce = ca.GetContactEntity(contactId);
The RESTful APIs are:
For the WebApi option, where have a new Library option SuperOffice.WebApi. This library wraps the WebApi Agents API, and is meant as a transitional API for integrations moving from the legacy WCF SOAP-based API to the HTTP option - the object models are nearly identical.
Also, in contract to the legacy SuperOffice.NetServer.Services package, which is only for usable with .NET 4.8 Full Framework compiled code, SuperOffice.WebApi is compiled to .NET Standard 2.0 and can be used by .NET 4.8, .NET Core and .NET 5 projects. See the SuperOffice WebApi article for more details.
Agents use Method-based signatures and are all POST requests, where as the pure REST endpoints use more traditional HTTP verb methods and url segment naming schemes.
Hope this helps!
Is there any guidence when to use RESTful Agents and RESTful REST?
I've been playing a little with the Agents api.It should refresh the access token when it's expired.I've noticed that if I tamper with the access token then a SuperOffice.Exceptions.WebApiException: Forbidden exception is thrown.Is this by design or should the access token be refreshed instead?
When to use which is largely your preference. The Agent API is complete, whereas the REST API lacks certain things, like Quote, and a few other minor things. These things are in the backlog.
In reference to AccessToken using the refresh token to auto-update, from the article (closest to docs at the moment):
I have no idea what you mean by "tamper" and therefore cannot comment on that. If you do not provide the necessary details that enable the AuthorizationAccessToken to refresh itself, you are required to aquire a new access token yourself and assign a newly instantiated AuthorizationAccessToken to the WebApiConfiguration/WebApiOptions.Best regards.