scionassociation/scion-cp_I-D

gRPC API - remove duplicated definitions in appendix

Closed this issue · 2 comments

nicorusti commented

With #24 we introduced a description of the gRPC CP API in the appendix. However, with this, some definitions are duplicated. For example, ASEntrySignedBody is defined in both 2.2.1.4.2. AS Entry Signed Body and in the appendix.

TODO:

  • evaluate wether we leave the gRPC API descriptions all in the appendix or in various paragraphs --> we leave them in both places
  • some gRPC definitions are duplicated, duplicates should be removed (preferably, leave them in the respective chapters rather than in appendix). A non-exhaustive list:
    • SegmentType
    • SegmentsRegistrationRequest
    • SegmentCreationService
    • BeaconRequest
    • BeaconResponse
    • PathSegment
    • SegmentInformation
    • ASEntry
    • ASEntrySignedBody
    • HopEntry
    • PeerEntry
    • HopField
    • SignedMessage
    • Header
    • HeaderAndBodyInternal
    • VerificationKeyID
  • make sure there are proper cross-references to the respective gRPC requests For example:
    • SegmentsRequest right now it is not clear which requests are used for path lookups by endpoints, e.g. we should mention that an endpoint sends a SegmentsRequest to its path server.
    • SegmentsResponse
    • SignatureAlgorithm
  • We sometimes call the API descritpions in the text "on Code-Level", we should use a better wording (e.g. gRPC API)
  • check descriptions and typos (e.g. // This API is exposed by the control services of core ASes expose this on the SCION dataplane and also by all
jiceatscion commented

I am not sure we should de-duplicated the APIs between text and index. The APIs in the text are for explanation purposes while the appendix is for reference. The appendix is there to make sure that we document the whole API. If we de-duplicate, then what do we name the appendix: "Those bits and pieces that we haven't mentioned somewhere in the document already"? That's not nice to future users of the spec.

  • 👍1
jiceatscion commented

I tried my best. Probably missed a spot or two.
There weren't many opportunities to reference the appendix. Most places had enough documentation in-line.
I couldn't remember if there was anything missing from the appendix. Was there?