0
\$\begingroup\$

I've been reading through the various questions asking whether or not API reviews are on topic, but they've left me a bit confused.

In particular "Are questions about public interface (API) on topic?" seems to suggest that API review questions are on topic as long as the code is included. However, sometimes a small API can have a large amount of backing code that wouldn't be suitable for this site. Or the code may not be written yet, but that doesn't mean there aren't objective points that could be made about the API to save someone time or help make their job easier later when they go to actually implement it.

To be clear, I'm not looking for a comparative "is this API better than this other API" or help designing an API, I'm specifically wondering if questions about a specific API design (listed in the question) are on topic. For example, if I posted something like the following Go-esq API (an early version of the actual API I'd like to ask about if it's deemed on topic):

// Mechanism represents an RFC 4422 SASL mechanism (eg. SCRAM-SHA-1 or PLAIN)
type Mechanism struct {
    Names []string
    Start func() (more bool, resp []byte, err error)
    Next  func(state State, challenge []byte) (more bool, resp []byte, err error)
    // contains filtered or unexported fields
}

// Err returns the last error generated by the mechanism.
func (c *Mechanism) Err() error

// Reset resets the mechanisms internal state machine so you can use it for another auth attempt.
func (c *Client) Reset()

// State returns the mechanisms internal state (see the State constants for more info)
func (c *Client) State() State

// Given a challenge from the server, Step attempts to advance the mechanism to its next state. It enforces directionality in the state machine and does not allow it to go backwards (unless reset resets it to the beginning).
func (c *Client) Step(challenge []byte) (more bool, resp []byte, err error)

// State is a represents the internal state of a Mechanism.
type State int8

const (
    Initial State = iota
    AuthTextSent
    ResponseSent
    ValidServerResponse
)

When asked for a review, someone might point out that if my mechanisms are stateful then you'll have to know your username and password when you decide what mechanisms are supported if you want to create a list of mechanisms as opposed to deferring needing to know them until the actual negotiation takes place. Or you'll have to have a list of mechanisms as sentinel values and map these to actual Mechanism constructors later, or they might point out that someone could construct a mechanism with a Start or Next function that was stateful itself, thereby breaking Reset's ability to effectively reset the state of the Mechanism. These are objective problems with the above API, but I never actually posted a line of code.

Would API review with a full, documented, API but no implementation like this be on topic?

\$\endgroup\$
3
\$\begingroup\$

No, this would be considered design-review, something explicitly off-topic at Code Review. No code: no review.

In the on-topic help centre, the following is considered off-topic:

  • Higher-level architecture and design of software systems

I'd say what you're proposing falls in that category.

\$\endgroup\$
  • \$\begingroup\$ I suppose I don't understand why that's off topic then; this isn't someone asking for design help, this is someone asking for review of a very specific design that will be tightly coupled with code. Is that not almost exactly the same as asking for a review of a database schema (which are in scope: meta.codereview.stackexchange.com/questions/149/…)? \$\endgroup\$ – Sam Whited Jul 16 '16 at 20:45
  • \$\begingroup\$ @SamWhited that post is very old, an admittedly we will do database design reviews as long as the code behind the database structure is included, but not otherwise. We are pretty strict however that this site is about reviewing code first, so if there is no code to review, it becomes off-topic. Likewise, if you would like your API (or parts of it) code-reviewed, then you would need to include the relevant code. \$\endgroup\$ – Phrancis Jul 16 '16 at 20:48
  • \$\begingroup\$ @SamWhited Databases are already in a grey area. Those being on-topic doesn't mean everything which looks like that is also on-topic. \$\endgroup\$ – Mast Jul 16 '16 at 20:48
  • \$\begingroup\$ Ah, so they're not actually on topic, gotcha. Thanks for the help. \$\endgroup\$ – Sam Whited Jul 16 '16 at 20:50
  • \$\begingroup\$ Reviewing design is not technically completely off-topic, it can be reviewed as part of the implementation. See meta.codereview.stackexchange.com/q/1924/31562 . Although I guess it depends on what you mean by "design". \$\endgroup\$ – Simon Forsberg Jul 16 '16 at 23:30
  • \$\begingroup\$ Oh, thanks, I hadn't seen that one. In my case (a version of the example API I posted, except significantly further along) I do have a completed implementation, however, I think the amount of code would be far too much to post on this site, so I'm a bit confused about how to proceed. \$\endgroup\$ – Sam Whited Jul 17 '16 at 14:09

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .