Page MenuHomePhabricator

Create endpoint
Closed, ResolvedPublic8 Estimated Story Points

Description

Context

For the API to adhere to requirements of the API Gateway, the endpoint must have:

  • conditional request headers (we can use etag or if-modified-since, but i think etag is preferred)
  • correct url structure {base URL}/{namespace}/v{version number}/{project name}/{subdomain}/{endpoint}
  • provide example of semantic versioning in endpoints
  • example using app-based oauth flow to read/write against a Wikipedia
Acceptance Criteria
  • Add logging to endpoint
  • Create tests for endpoint
  • Utilize storage
  • I can make a successful HTTP request
  • Example Node API description contains documentation for this endpoint

Event Timeline

sdkim set the point value for this task to 8.
sdkim moved this task from Incoming to Must do now on the API Platform board.

Per T288127: Design the Example Node API we intend to implement this iteratively. First steps seem to be:

  1. add the endpoint to spec.yaml, for documentation purposes and to clarify the initial path/behavior of the endpoint
  2. create a minimal endpoint implementation that returns a hard-coded "Hello World" string
  3. create one or more tests for this level of implementation

It probably makes sense to create subtasks for this.

Added three subtasks. This gets the basic boilerplate in place, which we can then expand on to fulfill the other acceptance criteria.

Looking a bit more, I don't see a reason not to use a simple hash of the response (md5 or whatever) as the etag value for the example api.

Also, kinda cool that the etag header documentation at mozilla.org uses a wiki as an example:
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag

It won't actually do much, but it at least provides a server-side example of how an ETag might be generated, and reinforces the idea that they're good things to have.

I suppose we could support an in-service cache that, if it detects If-None-Match (and has a cache entry for the associated etag) to return a 304 instead of the actual response. That'd be even more contrived for the example api, as regenerating the response is pretty cheap. But it'd give an example of that header's purpose. Not sure it is worth it, and if we did it we should add comments to the code explaining that it is just an example to illustrate functionality and not the way a real service should implement caching. Opinions welcome.