Bug 794435 (JBEPP-1476)

Summary: Improve REST API documentation
Product: [JBoss] JBoss Enterprise Portal Platform 5 Reporter: William Antônio <wsiqueir>
Component: DocumentationAssignee: Nick Scavelli <nscavell>
Status: CLOSED DEFERRED QA Contact:
Severity: high Docs Contact:
Priority: high    
Version: 5.2.0.GACC: dingham, epp-bugs
Target Milestone: ---   
Target Release: 5.2.1.GA   
Hardware: Unspecified   
OS: Unspecified   
URL: http://jira.jboss.org/jira/browse/JBEPP-1476
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2012-03-01 14:19:17 UTC Type: Enhancement
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description William Antônio 2012-01-10 20:22:55 UTC 
Affects: Documentation (Ref Guide, User Guide, etc.)
project_key: JBEPP

Hello,

I have been working with our EPP REST API it's a really great API. Unfortunately the documentation[1] has some obscure points. Here are some suggestions for improving the REST API documentation:


- The warn "All URL's below are relative to the REST management entry point of the portal container." is useful, but it doesn't mention what is the entry point. It would be great to know the entry point even if you use a clean installation as example;

- You should explore more the JSON part of the API. The JSON implements HATEOAS and after I found the first page I could navigate by all the API only using the HATEOAS feature;

- I would like suggest to give more examples using a clean EPP installation. The most good part of an API is to test it :-);

- I wish we could have something like .org documentation[2].

That's it, these are my suggestions.

[1] http://red.ht/uLBwDX
[2] https://docs.jboss.org/author/display/GTNPORTAL/GateIn+Management


Thanks.
Comment 1 hfnukal@redhat.com 2012-01-19 08:38:06 UTC 
Labels: Added: EPP_5_2_1_Candidate
Comment 2 Scott Mumford 2012-01-30 22:10:32 UTC 
Reassigning to EPP docs lead (Jared Morgan)
Comment 3 Thomas Heute 2012-02-16 09:59:57 UTC 
Labels: Removed: EPP_5_2_1_Candidate
Comment 4 Nick Scavelli 2012-02-20 21:04:04 UTC 
Hello William, please refer to below as response to your comments:

- The entry point is described in the main REST interface section here http://red.ht/sh9cfj. Let me know if you think adding it again would help.

- The read-resource operation (the operation that is executed for RESTful GET requests) is a global operation and it's REST response in JSON and XML is defined here: http://red.ht/z8TAYr.

- More examples would probably be good, but the REST API you link to is the REST API for the MOP management extension, which I just cover things specific to the MOP extension. The GET requests (read-resource operations) would basically be the same except for the children of each resource.

- The red hat docs are pretty much the same as the community docs, in terms of content since this is where we pulled from to create the product docs.