Best practice: Creating an API for my SmartGWT application

[Blama]

Hi Isomorphic,

I have a datacentric CRM-like application.
Now I have the requirement to import entries from many different sources. I started with an email import, that I integrated in the application as servlet that gets triggered via wget, fetches new data and creates entries via RPCManager-less DataSource operations. Next will be an interface to a CRM and afterwards to another and so on, where the (more mature) target systems all already have their own SOAP API.

Now I'm thinking that in the long run having a Connector-application separate from my application is better than integrating all these API calls in my application.
But this means I need to offer an API to my existing application (which is only accessible via IDACall so far), that can be used by my connector.

My question is how I design this API for my existing application best.

1. One obvious possibility is a Servlet plus writing a WSDL file and using JAX-WS with Axis2 (I'm using Tomcat 8) as start point.
2. Reading the QuickStartGuide it seems that it is also possible to use the SmartGWT serverside RESTHandler, but I do not know how to describe my allowed operations and their parameters, return type etc (as I do not have a WSDL description).

I think way#1 is the more independent one, but perhaps using RESTHandler is way easier. Do you suggest using RESTHandler? What are the downsides of using RESTHandler?

Thank you & Best regards
Blama

[Isomorphic]

We suggest using RestHandler.

It's true that in theory WSDL gives you a way to describe the operations. In practice, WSDL is so horrifically complicated and poorly designed that most people interested in your APIs would be relieved to see that you offer a simple REST API instead.

[Blama]

Hi Isomorphic,

OK, thanks for the advice. From my gut feeling I'd have chosen otherwise. How is this solved best using the RESTHandler?

1. Allow access only to some of my .ds.xml files/operationIds?
2. Authentication, as I can't rely on Realm Security / j_security_check here, correct?
   Educating myself on the topic I think that using an API key in the query string is the correct way (like e.g. the google maps API does)
3. My connector will use always use POST to access RESTHandler, correct (this answer of yours)?
4. How do I build the request to access RESTHandler in my connector? "Manually" string building with JSON or XML tools?
   The docs say:

   The RestDataSource provided with SmartClient is such a client, as is SmartGWT.mobile, but this handler will work with any REST client that encodes its data as JSON or XML, sends its requests as POST messages and conforms to the REST transfer protocol described in the client-side documentation for RestDataSource. Note that you must read these client-side documents in order to understand how to properly format a REST request for processing by this servlet.

   Therefore I assume this is really manual compared to WSDL generated service.
5. How do document my API? I assume this is not possible using Javadoc like tools that parse source code / annotations, correct? Perhaps copy & pasting requests & responses to a tool like Speca.io?

These questions go a bit into detail, but besides the tool choice in 5) all should be important to anyone building an API to their SmartGWT application, so they might be a valuable addition for the concept docs as well.
You wrote here that you can't doc every detail and I agree (also not everything can be read ;)), but having this not only in the forums would be of value I think.


Thank you & Best regards
Blama

[Isomorphic]

When comparing WSDL and REST, think carefully about the effort and what is "manual". You could start testing out RestHandler with a few lines of JavaScript and a quickly typed-up request now; just getting the right libraries and tools in place for WSDL takes a huge amount of effort, and the testing cycle is slow and error prone. Further, you require a much, much higher degree of knowledge from developers if you require WSDL-based integration.

For this reason, if you look around at most modern services that allow some kind of external automation (MailChimp, Firebase, etc), they provide REST first, then maybe WSDL later. Trend-wise for this kind of use case, WSDL is in a nosedive and REST is ascendant.

On your questions, taking these out of order:

3. without POST, you could not reasonably perform a transaction, or even safely use non-trivial AdvancedCriteria, because of the length limits on URLs
5. you might take a look at how Mandrill or Firebase or similar services document their APIs, or just lift relevant parts of the RestDataSource docs. REST is so simple, it doesn't take much to explain
4. anything you'd like; since there are no byzantine namespacing rules, there's little need for a client library and competent callers probably do not even need sample code
2. we don't really know the goals or competence of the people calling these APIs, but yes, an API key is a common approach
1. a servlet filter, or any other approach you like

[Blama]

Hi Isomorphic,

great, thank you. I'll definitely start with RESTHandler then and post back here in a few weeks.

Best regards
Blama