The URL listed against the details of identity resources returns 404 Not Found error

[Uday T Kumar]

Many of the details referencing the relationship between the operation and the resource return 404 Not Found when you try and follow the link.

For example, the details of the endpoint given against the following URL:

https://developer.openstack.org/api-ref/identity/v3/index.html?expanded=create-endpoint-detail#create-endpoint

Points to:

https://docs.openstack.org/api/openstack-identity/3/rel/endpoints

To describe the relationship but results in a 404 Not Found error.

This issue it consistent across many of the relationship links.

[Andreas Jaeger (jaegerandi)]

Uday, next time please use the "REport a bug link" at the top right - also a bottom right - to report this directly to correct repo.

[David Stanek (dstanek)]

Relationship links are not meant to be resolved. They are actually URNs. A URN is just like a GUID except is used a URI syntax so it is easier to read. keystone really doesn't do a full hypertext driven API, but if it did the URN is what you would use to find an actual URL to go to.

For example, in a document for a user representation there might be a dictionary key 'relationships' and the value would may URN to URL. So 'GET /user/1234' gives you a user representation. Then you could do something like 'user[relationships][http://does-not-exist#user-groups]' to find a URL that can be used to retrieve a user's groups.

This is sort of partially implemented and we don't seem to want people to use hypertext and instead want URLs hardcoded in clients. But that's really what this is for.

[David Stanek (dstanek)]

Feel free to reoen if this is actually causing issues in a deployment.

[Uday T Kumar (uday.t.kumar)]

I wanted to look at some sample outputs for this API but wasted some time with this. As I can see from other comments this is consistent across many pages. Therefore if this can be implemented, it might just save people their time and improve our documentation too.

Being just URN, one of the 2 things should be done:

1. Relationship paths could be modified from:
example (URL reported in bug) https://docs.openstack.org/api/openstack-identity/3/rel/endpoints

to:
to something like https://<sample URL>/api/openstack-identity/3/rel/endpoints

OR

2. Mention against this link saying its a URN.

[David Stanek (dstanek)]

I'm updating the docs to say that the URLs are not necessarily going to resolve to anything.

[Lance Bragstad (lbragstad)]

Adding this to the office-hours queue, since a documentation patch should be pretty easy to accomplish in a single session.

[Lance Bragstad (lbragstad)]

Moving this out of In Progress since I was unsuccessful in finding a patch in review that addresses this.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/491934

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/491934
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=6c8ea57210e91bac53268da2475e509071b575cf
Submitter: Jenkins
Branch: master

commit 6c8ea57210e91bac53268da2475e509071b575cf
Author: Gage Hugo <email address hidden>
Date: Tue Aug 8 16:25:38 2017 -0500

    Add description for relationship links in api-ref

    This adds a section within the index file that describes what a
    relationship link is and what it is used for in terms of each
    operation within keystone. There will be a relationships section
    in both v3 and v3-ext.

    This should help clarify any confusion that may arise when a user is
    viewing the api-ref about what the relationship links are.

    Change-Id: I9c6b7959ed6ea682c565c515af0cf509b6a64e5d
    Closes-Bug: #1674676

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 12.0.0.0rc1 release candidate.