getodk / getodk/central

Document Problem responses in API docs

Open
#768 0 comments 0 reactions 0 assignees View on GitHub
backend documentation
Dominant language
JavaScript
Stars
226
Forks
235
Avg merge
2d 22h
Merged PRs (30d)
19

Description

Quoting @lognaturel in Slack:

> We don’t currently document detailed error codes. It looks like the .1 variants are the only ones documented. Those codes can be really useful for clients and I’d like to use them in `pyodk`. … my understanding is that we could document 404.1, 404.2, etc separately with API Blueprint because there’s no semantics around HTTP error codes in the spec, the definitions are using standard data structures

The goals of this issue are:

- Document all Problem **codes**.
- For .1 variants only: Document the structure of the `details` property.

This won't fully document everything about Problem responses, but it would be a great first step.

Contributor guide

No contributing guide indexed for this repository

Research direction

No file is named in the issue. Start by locating the API Blueprint definitions for Problem responses and the currently documented .1 variants. Enumerate all Problem codes and document the details structure for .1 variants; the work is done when the API docs cover those codes and structures.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.