VocaDB REST API conventions

Riipah edited this page Jan 4, 2017 · 27 revisions

Terms

  • Path: URL without the query, for example /api/albums
  • Query: Query parameters in the URL, for example ?name=Miku
  • Safe: call does not change state
  • Idempotent: multiple calls have the same results (the state is replaced, not appended)

Note about idempotency

Almost none of the methods in the VocaDB API are truly idempotent. Versioning information changes even if no changes are made to the resource

  • Version number is incremented
  • New archived version is created
  • Activity feed entry is created
  • Modification date is updated

However, we consider the operation idempotent if the resource itself is replaced every time and not appended.

This means the idempotency in the VocaDB API is not "true" idempotency because it has side effects, but for practical purposes, we consider the operations idempotent.

Routes

  • Resource names are plural, for example /api/albums
  • Names with multiple words use camelCase, for example /api/releaseEventSeries and /api/users/profileComments
  • Generally as stateless as possible, with the exception of logged in user, for example /api/users/current
  • Resources are primarily identified by their unique ID which is an integer. However, child resources might be identified by multiple components of the path. For example, /api/users/{id}/ratedSongs/{songId} identifies user's rating for a specific song (the identifier consists of user ID and song ID).

Verbs

GET

  • For reading a resource.
  • Safe and idempotent (does not modify data).
  • No body, all parameters in query.
  • For example:
  • GET /api/songs?query=Miku (find songs by name)
  • GET /api/songs/3939/comments (get song comments)
  • GET /api/album/3939/tracks (get album tracks)
  • GET /api/users/current/songTags/3939 (get tags assigned to album by the current user).

POST

  • For creating or updating a resource when the URL is points to a collection or parent resource and the server determines the ID (which is the case when creating most resources on VocaDB).
  • Mostly commonly used for creating resources.
  • POST calls are not safe (they modify data), and generally not idempotent (multiple calls to the same URL yield different outcomes).
  • POST to collection appends new items to the collection.
  • Content in the body, even if just a single parameter.
  • Query parameters may be used to filter collection or otherwise control how the resource is to be updated.
  • For example:
  • POST /api/tags (create a new tag)
  • POST /api/users/{id}/profileComments (create a new profile comment)
  • POST /api/users/current/songTags/3939 (current user adds tags to song)

PUT

  • PUT is for creating or replacing (updating) a resource when the client identifies the resource to be created/updated in the URL.
  • Mostly used for replacing resources.
  • PUT calls are not safe (they modify data), but they are idempotent (multiple calls with the same content have no effect).
  • By default, PUT to collection replaces the whole collection. Collections can be filtered using query parameters, so that only some items are replaced.
  • Generally replaces the whole resource. PATCH will be used for partial updates.
  • For example:
  • PUT /api/users/current/songTags/3939 (replace tags assigned to song by the current user).

DELETE

  • For deleting resources.
  • For example:
  • DELETE /api/artists/{artistId} (delete an artist)
  • DELETE /api/users/profileComments/{commentId} (delete a profile comment). Note: user ID is not needed because the comment is uniquely identified by commentId.

PATCH

  • For partial updates, when only the changed properties are provided. Currently not used.

References

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.