[DOCU-2179] Request for feedback: on the "endpoint" term Created: 10/May/21  Updated: 21/Jul/21  Resolved: 22/Jun/21

Status: Closed
Project: Documentation
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Neutral
Reporter: Mikaël Geljić Assignee: Martin Drápela
Resolution: Done Votes: 0
Labels: external
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File image-2021-06-15-14-51-30-769.png     PNG File image-2021-06-15-14-52-56-071.png     PNG File image-2021-06-15-14-54-31-070.png     PNG File image-2021-06-15-15-08-11-684.png     PNG File image-2021-06-18-15-55-55-454.png     PNG File image-2021-06-18-15-56-37-646.png     PNG File image-2021-06-18-15-56-41-600.png     PNG File image-2021-06-18-15-57-35-113.png     PNG File image-2021-06-18-15-58-38-320.png     PNG File image-2021-06-22-12-51-27-505.png     PNG File image-2021-06-22-15-55-40-032.png    
Issue Links:
Relates
relates to MGNLREST-319 DOC: Content Management API Closed
Documentation page URL: https://docs.magnolia-cms.com/product-docs/Developing/API/REST-API/Delivery-endpoint-API/Delivery-endpoint-API-v2.html

 Description   

Coming over from SUPPORT-13005, when talking about our Delivery API, I often end up referring to our docs, end there it says Delivery endpoint API v2, which first, reads awkward.

Second, the "endpoint" term is in fact quite ambiguous for many users. Some confuse it with API (actually we do*, in our code), some with "resources", etc.

* As I stated in my comment on SUPPORT-13005, I would argue that the Delivery API consists of 3 endpoints (or whatever we prefer to call them). So I would not refer to the grouping entity as endpoint anymore. Conversely, I'd consider an alternative name to the "rest-endpoints" directory in future iterations of light-development.

In a first step, it would be interesting to compare with a few CMS/REST docs how those different locators within APIs are called, and consider tuning our docs. What do you think about that? Any opinion? gut-feeling what it would take?

Additionally, we might consider simplifying the API tree of our docs as well, e.g.

  • API
    • Delivery API (would ditch v1 docs by now)
    • SPA Template Definitions API (would list both /template-definitions and /template-annotations under the same API page here)
    • GraphQL API
    • Commands API
    • Nodes/Properties API (legacy)
  • Java Server APIs
    • JCR API
    • DAM API
    • ...

Generated at Mon Feb 12 01:24:45 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.