[Schema Inaccuracy] `/repos/{owner}/{repo}/git/trees` can respond with an undocumented 409

Open
#637 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

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

Research direction

Start at the documented POST /repos/{owner}/{repo}/git/trees operation and compare its responses with the corresponding git/blobs documentation. Verify the empty-repository 409 behavior using the reproduction, then update the endpoint's documented responses and condition once the intended behavior is confirmed.

Written by the indexing model from the issue text.

Description

feature fundamentals-and-support inaccuracy P4 shield waiting for review

Schema Inaccuracy

The route is documented as responding with 403 (forbidden e.g. use doesn't have write access), 404 Not Found (repo does not exist?) or 422 Unprocessable Entitiy (both sha and content specified? possibly also invalid mode, or type?)

However it can also reply with an HTTP 409 Conflict iff the repository is empty, while this is not clearly noted /repos/{owner}/{repo}/git/blobs does document the response code and behaves the same.

Expected

Either documenting the error condition, or allowing the creation of trees and blobs in empty repositories.

Reproduction Steps

import base64
import os

import requests

# add `token` to test with here

s = requests.Session()
s.headers['Accept'] = 'application/vnd.github.v3+json'
s.headers['Authorization'] = f'token {token}'

owner = s.get('https://api.github.com/user').json()['login']
repo = 'test_' + base64.b64encode(os.urandom(6), b'-_').decode()

r = s.post('https://api.github.com/user/repos', json={
    'name': repo,
    'has_issues': False,
    'has_projects': False,
    'has_wiki': False,
    'auto_init': False,
    # at least one merge method must be enabled :(
    'allow_squash_merge': False,
    # 'allow_merge_commit': False,
    'allow_rebase_merge': False,
})
r.raise_for_status()
r = s.post(f'https://api.github.com/repos/{owner}/{repo}/git/trees', json={
    'tree': [{
        'path': 'a',
        'mode': '100644',
        'type': 'blob',
        'content': 'this is my content'
    }]
})
print(r.status_code, r.reason)
for k, v in r.headers.items():
    print(f'{k}: {v}')
print()
print(r.text)
Dominant language
No language data
Stars
1.6k
Forks
342
Avg merge
3h 33m
Merged PRs (30d)
51

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/rest-api-description

All issues in github/rest-api-description

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.