Bug 1013293

Summary: The application level APIs of version 1.6 do not match the official documentation
Product: OpenShift Online Reporter: Zhe Wang <zhewang>
Component: MasterAssignee: Clayton Coleman <ccoleman>
Status: CLOSED CURRENTRELEASE QA Contact: libra bugs <libra-bugs>
Severity: medium Docs Contact:
Priority: medium    
Version: 2.xCC: ccoleman, pruan, xtian
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2013-10-17 13:32:42 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Zhe Wang 2013-09-29 06:38:41 UTC
Description of problem:
When showing the application level APIs, all the hrefs are using https://<broker_DNS>/broker/rest/application/:id (singular of application), while in the official document (http://openshift.github.io/documentation/rest_api/rest-api-1-6.html#application), the APIs are using "applications" (https://<broker_DNS>/broker/rest/applications/:id). Moreover, the APIs referrer in the documentation are not accessible.

Version-Release number of selected component (if applicable):
devenv_3844
REST API 1.6

How reproducible:
always

Steps to Reproduce:
1. create an app
2. get the API list of this app
3. try to stop the app with the corresponding API http://openshift.github.io/documentation/rest_api/rest-api-1-6.html#application
4. try to stop the app with the corresponding API returned in Step 2

Actual results:
In Step 2, all the app level APIs are using "application/:id" as its suburl, for example,

 "STOP": {
                "href": "https://ec2-23-20-54-119.compute-1.amazonaws.com/broker/rest/application/524795154974f504e3000010/events", 
                "method": "POST", 
                "optional_params": [], 
                "rel": "Stop application", 
                "required_params": [
                    {
                        "description": "event", 
                        "invalid_options": [], 
                        "name": "event", 
                        "type": "string", 
                        "valid_options": [
                            "stop"
                        ]
                    }
                ]
            }, 

In step 3, it fails when trying to stop the app with the official API (applications/:id), and the error is 

<h1>Routing Error</h1>
<p><pre>No route matches [POST] &quot;/broker/rest/applications/524795154974f504e3000010/events&quot;</pre></p>
<p>

On the other hand, it works when using the href returned in Step 2 (application/:id)

    "messages": [
        {
            "exit_code": 0, 
            "field": null, 
            "index": null, 
            "severity": "info", 
            "text": "Application spy27 has stopped"
        }
    ], 


Expected results:
The application leve APIs should be consistent with those in the official documentation of REST API 1.6.

Additional info:

Comment 1 Lili Nader 2013-10-01 19:04:56 UTC
Verified that the links with applications (plural) still work.  Reducing severity to low.

Comment 2 Peter Ruan 2013-10-09 06:28:57 UTC
for gear_groups the old route does not work.

/broker/rest/applications/<app-id>/gear_groups.json

Comment 3 Zhe Wang 2013-10-09 07:18:01 UTC
It turns out that all the sub urls referencing the plural form "applications" does not work in INT(devenv_3864) and devenv-stage_488, for example:

/broker/rest/applications/:id/events.json

(the corresponding hrel returned in the responses is /broker/rest/application/:id/events which actually works)

but this API format of plural form is usable in current STG(devenv-stage_486).

Comment 4 Xiaoli Tian 2013-10-09 10:36:32 UTC
Raise its severity to medium since it's a regression in sprint34  in case some customers or external tools are already using /broker/rest/applications/:id/. 

Devel could double confirm if it's still low severity.

Comment 5 Clayton Coleman 2013-10-09 19:33:08 UTC
Documentation should be updated.  Old URLs are still supported.  Gear-groups was fixed by bug 1017000

Comment 6 Clayton Coleman 2013-10-10 13:48:44 UTC
Made some minor changes in https://github.com/openshift/origin-server/pull/3832

Comment 8 Clayton Coleman 2013-10-11 18:44:59 UTC
Fixed in master, not in STG. Does not need to go to STG for sprint 34 because doc is built off master.

Comment 9 Zhe Wang 2013-10-12 08:57:59 UTC
The dcs are now matched with the APIs, move the bug to VERIFIED.