Document /v3/firefox/save

NEW
Unassigned

Status

()

Firefox
Pocket
3 years ago
2 years ago

People

(Reporter: Yoric, Unassigned)

Tracking

Trunk
Points:
---

Firefox Tracking Flags

(firefox42 affected)

Details

Pocket places calls to API "/v3/firefox/save". This call doesn't look documented yet. It needs to be documented.

Comment 1

3 years ago
Pocket places calls to API "/v3/getSuggestedTags" as well which also doesn't appear to be documented.
(In reply to David Rajchenbach-Teller [:Yoric] (use "needinfo") from comment #0)
> It needs to be documented.

This kind of entitlement without a clear rationale rubs me the wrong way. This is a Firefox-specific Pocket endpoint, documenting it doesn't seem particularly necessary or high priority, and tracking its documentation in our Bugzilla doesn't really make sense.
> This kind of entitlement without a clear rationale rubs me the wrong way. 

I'm probably missing something. This is a case of Firefox using a (so far) undocumented protocol. I don't see a good reason to not make it a documented protocol. Plus Documentation Is Always Good (tm).
> I don't see a good reason to not make it a documented protocol.

I think the burden of proof goes the other way. What purpose would it serve?
Well, undocumented code (and protocols) hinders reviews, maintenance, contributions, refactorings and feature evolution. While this specific piece of code also has a political/PR baggage, which makes discussions on it complicated, I don't see any reasons why it should not strive to support all of the above.

Comment 6

2 years ago
It should be noted that I agree this is should not be a high priority.  I believe the priority status put on this was normal.  However, I disagree that it is not particularly necessary.

Having a documented API regardless of if the function call is to the local OS or to a remote service in a RPC style (such as this case) would be for the purpose of the following:

- Make it more easily accessible to others on what data is transferred from the browser (Mozilla Manifesto Principle #4)

- Encourage discussion on how the API could be improved or what features could be added (Mozilla Manifesto Principle #5)

- Help encourage interoperability with the API (Mozilla Manifesto Principle #6)

- Improves transparency (Mozilla Manifesto Principle #8)

While it has been pointed out previously that the integration is consistent with Mozilla Manifesto Principle #9 (which I am not disagreeing with), I don't think that needs to be at the exclusion of the other principles.
You need to log in before you can comment on or make changes to this bug.