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

• http://www.japsportal.org/api/it/getServices
• http://www.japsportal.org/api/it/getContents

Anatomy of a GET call


Given: http://www.japsportal.org/api/it/getServices


We have:

http://www.japsportal.org
    The basic URL of a portal we know it's eager to receive such a call
/api/
    The root, the starting point of the API ''domain''
/it/
    ''entando'' is multilingual by design, thus we specify the language for the result
/getServices
    The method we want to call  


Sample Results


Given: http://www.japsportal.org/api/en/getServices

If the requested method has been disabled by the administrator

Notes

• 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

Notes

• 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


Given: http://www.japsportal.org/api/en/getService?sid=SOMECODE 

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

/WEB-INF/plugins/jpwebmail/aps/api/get/services/INBOX_INTRO/description-item.vm

Notes

• 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