Document result codes and possible content if track upload fails

[amandel]

Might be a link to the source code would be enough documentation :)

With openbikesensor/OpenBikeSensorFirmware#193 we started the idea to return the link to the new uploaded track as body of the response. This can allow easy navigation to the track after upload.

Today there are more none technical errors detected on the portal which deserve a error code like 409 if the track is already uploaded etc. Might be this is already the case, I did not look into the code ;).

[gluap]

Digging a little my result is: currently we're returning Code 400 (InvalidUsage) for duplicate tracks. We're not overly specific in what we return yet. This is the implementation of /tracks on the server side:

portal/api/obs/api/routes/tracks.py

Lines 90 to 129 in ee6163b

	async def post_track(req):
	try:
	file = req.files["body"][0]
	except LookupError as e:
	raise InvalidUsage(
	'Track upload needs a single file in "body" multipart field'
	) from e
	try:
	body = req.json["track"]
	except (LookupError, InvalidUsage):
	body = {}
	title = body.get("title")
	public = body.get("public")
	track = Track(
	title=title,
	customized_title=bool(title),
	author=req.ctx.user,
	public=public
	if public is not None
	else req.ctx.user.are_tracks_visible_for_all,
	)
	track.generate_slug()
	try:
	await track.prevent_duplicates(req.ctx.db, file.body)
	except DuplicateTrackFileError:
	raise InvalidUsage("Track file is not unique")
	track.uploaded_by_user_agent = normalize_user_agent(req.headers["user-agent"])
	track.original_file_name = file.name
	await track.write_to_original_file(req.app.config, file.body)
	track.queue_processing()
	track.auto_generate_title()
	req.ctx.db.add(track)
	await req.ctx.db.commit()
	return await get_track(req, track.slug)

[opatut]

In principle, any code outside the 200s range is an error. The shape of the error response body doesn't make me happy yet so please try not to use it ;)

The response is a JSON encoded track object, so it has its own slug in there and you can build the URL yourself. Isn't that enough?