Friday, April 8, 2011

What is that API thing everybody is chattering about?

Don't know very well, but in the meantime Eugenio and me are going up to the edge of the hill just to see if we can manage to give some hApPIness to the amazing world of jAPS 2.0 entando.
Seriously, look what I discovered seconds ago in my hard drive...
Evidence A:

Strange kind of message from the outer space
Evidence B:
Strangest kind of message from the outer space ever 
No. Seriously. Look at what Eugenio forced me to write.
Anyone able to understand the language down there, out there?
Classified TOP SECRET

API, REST, and stuff 

Sample GET calls
Anatomy of a GET call


We have:
    The basic URL of a portal we know it's eager to receive such a call
    The root, the starting point of the API ''domain''
    ''entando'' is multilingual by design, thus we specify the language for the result
    The method we want to call  

Sample Results


If the requested method has been disabled by the administrator

  • the root element services is named after the method getServices, chomping away the get and then making the remaining part all lowercase.
  • the result is empty because an error occurred ''and'' because there's nothing to return as a result.
  • we'd like to use the element item every time we have a collection of ''things'' in a result (but of course there might be just one item in a result, so this explanation about collections seems a bit confusing).
If the requested language is not available for that ''entando'' instance

  • The default language, the system one, is English. Thus in this very case the message is always returned in English.
If all is going well, and the system can answer the request

More sample results


sid=CNTS_NWS - If all is going well, and the system can answer the request

sid=JPWEBMAIL_INBOX_INTRO - If all is going well, and the system can answer the request
Because of JPWEBMAIL_INBOX_INTRO being a badass and smart service well crafted by the mighty hand of a developer, thus not configured in the back-office by the administrator as the News above, the developer's bat-companion had hopefully his chance to score a point in crafting a proper velocity model for the description in


  • we still need to conquer the ''multi-language by design'' thing here
  • you will choose the informations ( $item.unread ) wisely amongst the ones in the ''Serialized Object'' part of the result
  • in ''entando'' there will be some routine able to cycle on items and apply that velocity model to each and every item
Concerning description
  • a smart and proper summary, almost never complete with all the data available
  • it have to worthily respond to the needs of who made the request (Example: I want the weather forecast. You'll not include millibars and small details in the description
  • it must be easily placeable, with a few or no constraints: no headings ( h1, h3) and the like; maybe also no paragraphs when applicable


Anonymous said...

Have you found something about authentication and security in your hard drive? :)

Wiz of Id said...

At this stage we are focusing on the basic (well, maybe quite not so basic) features, all of them "read-only" and available to everyone.

Then, authentication and per-user / group settings and calls will follow for sure :)

But don't take it as a list of defined priorities...

Eugenio is kinda "creative" when it comes to pushing useful features in a software when I'm looking the other way... ;-)