Agents & REST - when to use what?

RE: Agents & REST - when to use what?

Hi Patrick,

You probably already know, but for other readers who don't, we have three API options:

1. SOAP
2. RESTful Agents
3. RESTful REST

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:

• WebAPI Agents, where all methods are POST requests. Notice how the URL for the Agent uses Method name segments...this is the key different between WebApi Agents and WebApi REST

POST /api/v1/Agents/Contact/GetContactEntity?contactEntityId=5

• pure RESTful API uses the traditional HTTP GET, PUT, POST, PATCH, DELETE methods.

GET /api/v1/Contact/5

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.

TL;DR

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!

RE: Agents & REST - when to use what?

Hi,

Is there any guidence when to use RESTful Agents and RESTful REST?

• Are the two feature complete compared to each other?
• Will the two support the same features in the future or is one of them considered "first choice"?

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?

Thanks!

RE: Agents & REST - when to use what?

Hi Gunnar,

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.