API reference contains mistakes

Bug #1760644 reported by Oleksiy Petrenko on 2018-04-02
14
This bug affects 2 people
Affects Status Importance Assigned to Milestone
Manila
Medium
Goutham Pacha Ravi

Bug Description

I'm writing a custom client for manila API and I tried to use the official manila API reference
(https://developer.openstack.org/api-ref/shared-file-system/)

So far I've encountered the following problems:

- Manage share method must be POST, not GET
- List share methods in fact do not accept many parameters in request body despite they are described in api-ref as 'body' parameters (e.g. name) - it looks like they must be of 'query' type in the API ref. Also, some request options have descriptions clearly copy-pasted from POST methods (e.g is_public).

Changed in manila:
status: New → Triaged
importance: Undecided → High
Tom Barron (tpb) wrote :

Thanks for this report.

Any chance that you are willing to submit a patch or patches to address some of these issues? We'd be happy to help shepherd the patches through the review process.

Changed in manila:
assignee: nobody → Victoria Martinez de la Cruz (vkmc)
summary: - API refference contains mistakes
+ API reference contains mistakes
Tom Barron (tpb) on 2018-06-19
tags: added: docs
Tom Barron (tpb) on 2018-06-19
tags: added: api-ref doc
removed: docs
Sneha Prasad (snpd) wrote :

If no work has been done, can I take this issue?

Sure Sneha, go ahead!

Changed in manila:
assignee: Victoria Martinez de la Cruz (vkmc) → nobody

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

Changed in manila:
assignee: nobody → Goutham Pacha Ravi (gouthamr)
status: Triaged → In Progress
Goutham Pacha Ravi (gouthamr) wrote :

Sneha: This is an "epic" bug, there are lots of fixes that can be made incrementally until we're satisfied we have weeded out the mistakes the OP encountered. Please feel free to submit patches.

Changed in manila:
assignee: Goutham Pacha Ravi (gouthamr) → nobody
status: In Progress → Triaged
Goutham Pacha Ravi (gouthamr) wrote :

https://review.openstack.org/648005 is just a partial fix fixing some missing parameters.

Changed in manila:
assignee: nobody → Goutham Pacha Ravi (gouthamr)
status: Triaged → In Progress
Goutham Pacha Ravi (gouthamr) wrote :
Changed in manila:
assignee: Goutham Pacha Ravi (gouthamr) → nobody
Changed in manila:
assignee: nobody → Goutham Pacha Ravi (gouthamr)

Reviewed: https://review.openstack.org/647973
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=5cd643785d81784d61e4d9b49ff0707ff5dd4ed9
Submitter: Zuul
Branch: master

commit 5cd643785d81784d61e4d9b49ff0707ff5dd4ed9
Author: Goutham Pacha Ravi <email address hidden>
Date: Tue Mar 26 18:42:44 2019 -0700

    [doc][api-ref] Clarify manage/unmanage APIs

    Clarify the usage of these APIs wrt DHSS=True/False
    drivers.

    Partial-Bug: #1818758
    Partial-Bug: #1760644
    Change-Id: I0fb239a44dee5b2c8da1d469ae761e780d14b4b2

Changed in manila:
assignee: Goutham Pacha Ravi (gouthamr) → nobody

Reviewed: https://review.openstack.org/648005
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=41d243c3948b041d46e516380212e41b128baa49
Submitter: Zuul
Branch: master

commit 41d243c3948b041d46e516380212e41b128baa49
Author: Goutham Pacha Ravi <email address hidden>
Date: Tue Mar 26 20:14:42 2019 -0700

    [doc][api-ref] Fix annotation and missing parameters

    - Call out the maximum API version in Stein (2.49)
    - Add parameter 'cast_rules_to_readonly' to share instance API ref
    - Remove parameters 'export_location' and 'export_locations' from
      share instance API ref.
    - Add "min_version" and "max_version" annotations on parameters
      where missing.
    - Add "versionadded" annotation to APIs
    - Add "DEPRECATED" annotation to deprecated APIs along with
      a warning message.

    Identical changes to the manage/unmanage APIs are handled
    in https://review.openstack.org/#/c/647973/

    Partial-Bug: #1760644
    Change-Id: I5342cc26d1cbeea8ca3d55868e0f69d525333421

Changed in manila:
assignee: nobody → Goutham Pacha Ravi (gouthamr)

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

Reviewed: https://review.openstack.org/623559
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=d7140ffe0915655652ae5b8308fbd519a26b9851
Submitter: Zuul
Branch: master

commit d7140ffe0915655652ae5b8308fbd519a26b9851
Author: Thomas Bechtold <email address hidden>
Date: Fri Dec 7 19:55:30 2018 +0100

    [api-ref] Replace "tenant" terminology with "project"

    Nowadays "project" and "project_id" are used instead of "tenant" in
    the OpenStack world. See [1] and [2].

    - Replace "tenant_id" in the API paths to "project_id"
    - For most manila resources, the "project_id" in an API response body
      refers to the project that owns the resource. So, create a unified
      parameter and share that across the APIs.
    - Fix path variable names, and their order
    - Fix usage of "UUID" to refer to project and user IDs
    - Fix query parameters

    [1] https://docs.openstack.org/operations-guide/ops-projects-users.html
    [2] https://developer.openstack.org/api-ref/identity/v3/index.html#projects

    Partial-Bug: #1760644
    Co-Authored-By: Goutham Pacha Ravi <email address hidden>
    Change-Id: I64e4ef8ad258d07c7d80d11a4d015c4b82156722

Reviewed: https://review.openstack.org/648547
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=f185ff0f446102c28bf333bb8c531ccb85a07744
Submitter: Zuul
Branch: master

commit f185ff0f446102c28bf333bb8c531ccb85a07744
Author: Goutham Pacha Ravi <email address hidden>
Date: Thu Mar 28 14:56:08 2019 -0700

    [api-ref] De-duplicate date and time parameters

    Many APIs present information when the resource
    in question was 'created_at' and 'updated_at'.

    Having common parameters is easier to maintain in
    the documentation since the description is the same
    across the board.

    Change-Id: Ia5d4ac399fe0d7983c61f5c5e0245d0987e97d6a
    Partial-Bug: #1760644

Reviewed: https://review.openstack.org/648568
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=5bf0337396b108623eb240efb4794ec2ded323fd
Submitter: Zuul
Branch: master

commit 5bf0337396b108623eb240efb4794ec2ded323fd
Author: Goutham Pacha Ravi <email address hidden>
Date: Thu Mar 28 17:48:10 2019 -0700

    [api-ref] De-duplicate name and description parameters

    Many resources in manila have user-defined
    names and descriptions. All of them have the
    same restrictions that apply, so represent them
    as the fewest parameters needed.

    Having common parameters is easier to maintain in
    the documentation.

    Change-Id: Ib175e8d78e4240bf40d87a47af2459ac520fb24a
    Partial-Bug: #1760644

Reviewed: https://review.openstack.org/648796
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=4ffca949c20d46434f82e549bb406bd5706b686a
Submitter: Zuul
Branch: master

commit 4ffca949c20d46434f82e549bb406bd5706b686a
Author: Goutham Pacha Ravi <email address hidden>
Date: Fri Mar 29 16:28:35 2019 -0700

    [api-ref] Delete unused parameters

    TrivialFix
    Related-Bug: #1760644
    Change-Id: I0eb4282b9162ba8ab83abb925828d5b1cfb333b2

Changed in manila:
assignee: Goutham Pacha Ravi (gouthamr) → Tom Barron (tpb)

Reviewed: https://review.openstack.org/617175
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=2736d4adcc7d5f8d8d41ae040d31557a77a2a717
Submitter: Zuul
Branch: master

commit 2736d4adcc7d5f8d8d41ae040d31557a77a2a717
Author: shaoxj <email address hidden>
Date: Mon Nov 12 09:43:07 2018 +0800

    The parameters of 'list shares' are optional

    Only 'project_id' in the path is required,
    other parameters are not required

    Partial-Bug: #1760644
    Change-Id: I8f5735f8b828f33c95139e5a963f56b5b6e9105a

Fix proposed to branch: master
Review: https://review.opendev.org/673112

Changed in manila:
assignee: Tom Barron (tpb) → Goutham Pacha Ravi (gouthamr)

Reviewed: https://review.opendev.org/673112
Committed: https://git.openstack.org/cgit/openstack/manila/commit/?id=b39bc70093f0d263e7df6d144a785a5b3b58ea25
Submitter: Zuul
Branch: master

commit b39bc70093f0d263e7df6d144a785a5b3b58ea25
Author: Goutham Pacha Ravi <email address hidden>
Date: Fri Jul 26 15:00:21 2019 -0700

    [api-ref] Correct share metadata API ref

    - Clarify the difference between PUT and POST
      on the /shares/<ID>/metadata URL
    - Add ref for API to retrieve a single metadata
      item
    - Add more notes regarding API behavior

    Partial-Bug: #1760644
    Change-Id: Ic976e0436584b86938c96db571022e96b4592d1f

Goutham Pacha Ravi (gouthamr) wrote :

A lot of fixes have been made to the api-ref - I'm closing this catch-all bug as Fixed at the moment. If there are specific mistakes that we find after these fixes, new bugs can be opened and actioned upon.

Changed in manila:
importance: High → Medium
status: In Progress → Fix Released
milestone: none → train-2
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Duplicates of this bug

Other bug subscribers