REST API设计疑问：APP最新版本查询接口的请求方式与路径设计

Hey there! Let’s work through your REST API design problem together—this is a super common dilemma, so you’re not alone.

First, let’s address the core issue: you’re stuck between GET (which can’t handle your long/variable JSON params) and POST (which feels like it breaks REST semantics for a query operation).

Here’s the thing: REST conventions aren’t hard rules, and there are exceptions for practicality. If your parameters are truly too long to fit in a URL (most servers/browsers cap URLs around 2-8KB), using POST for a query is acceptable—as long as you document it clearly and ensure the operation is idempotent (multiple identical requests return the same result, no side effects). Many major APIs (like Elasticsearch’s search endpoint) do this for complex queries, so it’s a widely accepted workaround.

Alternatively, see if you can refactor some of your parameters into path variables instead of a JSON body. For example, if you’re filtering by app ID or OS type, those can live in the URL (e.g., /xxxx/apps/{app-id}/latest-version?os=android), which might reduce the size of the remaining params enough to fit in a GET request.

Let’s break down this path:

• Naming consistency: REST paths typically use kebab-case for readability, so latest-version is better than latestversion.
• Resource clarity: The path feels a bit vague. If this endpoint returns the latest version’s package info (including download URL), it’s missing a key detail: which app? If you’re building an API for multiple apps, you should include an app identifier (like an ID or slug) in the path (e.g., /xxxx/apps/my-cool-app/latest-version). Without this, the endpoint only works for a single hardcoded app, which limits scalability.
• Redundant package: The word package might be unnecessary if the endpoint’s purpose is to return the latest version’s details (including the download URL). If you need to specify a package type (e.g., APK vs IPA), use a query parameter instead (e.g., ?package-type=apk)—this keeps the path focused on the resource (the latest version) and uses params for filtering.

A revised, more REST-friendly path might look like:

/xxxx/apps/{app-identifier}/latest-version

1. Request method: If params are too long for GET, use POST with a JSON body, but document that it’s an idempotent query operation (not a create/update).
2. Path design: Refactor to include an app identifier, use kebab-case, and move filtering params to query strings instead of cluttering the path.

内容的提问来源于stack exchange，提问作者Foredoomed