API documentation error?

Development

AI-generated summary

The discussion revolves around an API documentation error. Julian_Elve points out that the documented GET /admin/users/{id}.json endpoint is not working and instead suggests GET /admin/users/{id}/{username}.json. However, Mittineague disputes this, stating that the first path works as long as it’s a valid member ID number.

The conversation reveals that Julian_Elve is running Discourse 2.1.1, while Mittineague is on 2.2.0.beta2, which might explain the difference. Mittineague also shares that multiple variations of the endpoint work for them, including .../admin/users/{userid}.json.

Julian_Elve realizes that the issue might be due to not using the .json suffix and instead relying on the Accept header. Mittineague suggests that routing differences might be the cause and recommends using the Ember addon to inspect the API. Julian_Elve installs the addon and begins to investigate further, considering the possibility of reverse-engineering the API.

1

At this page the documentation states that detailed record for user can be obtained by GET /admin/users/{id}.json

Tests suggest this is not correct (returns 404) and the correct URL is GET /admin/users/{id}/{username}.json

Should I do a PR on the docs repo? Or do the team consider that the API expresses what the API should do, so this is actually an API bug?

Julian

2

I think you should revisit your tests. The first path works fine as long as it is a valid member id number

In fact, AFAIK, it is the only path that works with the account number and not the member name.

3

Sorry @Mittineague I’m absolutely positive. Maybe this is a version change? I am running against Discourse 2.1.1

You can also see it -in the UI - when you look at details of a user they appear at
<mysite.com>//admin/users/{userid}/{username} while <mysite.com>//admin/users/{userid}/ is a 404

4

You have a few variations there. These work for me.
Discourse 2.2.0.beta2
.../admin/users/{userid}.json
.../admin/users/{userid}/{username}
.../admin/users/{userid}/{username}.json

5

That one works for me too. I’ve been ignoring the .json suffix and just using the header as documented

Instead of sending API requests to /categories.json you may also send them to /categories and add an Accept: application/json header to the request to get the JSON response. Sending requests with the Accept header is necessary if you want to use URLs for related endpoints returned by the API, such as pagination URLs. These URLs are returned without the .json prefix so you need to add the header in order to get the correct response format.

but maybe I need to change my code to use it.

6

Routing is different for different paths. Do you have the Ember addon installed in your browser?

7

I have now - so this is about reverse engineering the API?