Very poor REST APIs documentation for all Atlassian products

Question

Hi,

Am I alone to find that the documentation for REST APIs for Jira, Confluence and Crowd are very poor, are missing lots of details (missing parameters, missing sample JSON body to sent, missing JSON responses, ...) ?

For Jira & Confluence, the REST API browser plugin allows getting some missing details but for Crowd, it seems that only the online doc is available.

One example :

I want to add a user in a group, I read the doc :

https://docs.atlassian.com/atlassian-crowd/3.5.0/REST/#usermanagement/1/user-addUserToGroup

I have one "username" parameter. Ok, but how do I identify the group ??

It's a pity that we have to look for code samples on the web each time we want to make a call to a REST endpoint and discover that some parameters are not documented ...

What's your opinion ?

Thanks

Eddy

Eddy Fras · Answer

Hi Brant,

Thanks for your answer.

You're right, having a more attentive look at the schema, it gives details on the json data to send but we still miss a lot of information : explanation of the fields, are they required or optional ?, ...

Let's take another example, "Add user" : https://docs.atlassian.com/atlassian-crowd/3.5.0/REST/#usermanagement/1/user-addUser

According to the schema, I have to send :

* "directory-id" and "directory-name" => it doesn't work, the user is added in the first directory of the application in Crowd.

* "created-date" and "updated-date" => it doesn't work, these dates are automatically set to the user creation date using the API

And coming back to "Add user to group" : https://docs.atlassian.com/atlassian-crowd/3.5.0/REST/#usermanagement/1/user-addUserToGroup

According to the schema, I have to send :

* "name" => we have to guess this is the group name but ok, it's quite straightforward

* "description" => is it mandatory ? it seems no ...

* "type" => I guess what "GROUP" value means but what about "LEGACY_ROLE" value ?

And I think I can find lots of other examples where actually I have to test all options first to get the real specs of the API.

Eddy

Brant Schroeder · Answer

Eddy,

The API documentation is actually pretty good and I have never had an issue with it.  In the example you are describing above I wonder if you just happened to miss the schema.  If you look at the schema it has everything you need to use the rest api.  If you expand it you can see all the details. (See Screenshot Below)  Hopefully this helps, I would feel the same way as you without this information.