Am I looking in the wrong place for Sharepoint Developer Documentation?

[TexasTechnician]

What type of issue is this?

Question

What SharePoint development model, framework, SDK or API is this about?

SharePoint REST API

Target SharePoint environment

SharePoint Online

What browser(s) / client(s) have you tested

• 💥 Internet Explorer
• 💥 Microsoft Edge
• 💥 Google Chrome
• 💥 FireFox
• 💥 Safari
• mobile (iOS/iPadOS)
• mobile (Android)
• not applicable
• other (enter in the "Additional environment details" area below)

Additional environment details

• browser version
• SPFx version
• Node.js version
• etc

Issue description

I'm looking for a straight-forward list of Sharepoint REST API endpoints and methods. So far I've found little tid-bits of information scattered throughout the official documentation.

For example I can't find any documentation about this URI: _api/web/siteusers

Every API ive dealt with has a full list of every possible endpoint and clear examples of how to use them. SharePoint's documentation is all over the place. There doesn't seem to be any clear structure to the documentation.

I mean look at this: Big Commerce API
And then try to figure out how to get a list of brands from a big commerce store.
Answer: https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands

And then look at this: SharePoint API
And then try to find a specific site's user by their email address through an HTTP Request.
Answer: https://{TENAT NAME}/.sharepoint.com/sites/{SITE NAME}/_api/web/siteusers/GetByEmail('{EMAIL})
I got that answer from the Power Automate form btw, 90% of everything I've found about sharepoint's API I've gotten from peoples blogs.

Is there some secret documentation that I don't know about? (if its right in my face the whole time, POINT IT OUT PLEASE!)
Is there a way to search Microsoft documentation which doesn't bombard me with 2,000,000 hits that have nothing to do with my query?
Reference:

Or am I forever doomed to search endless blogs and support forums?

Someone please, throw me a bone.

Thank you for reporting this issue. We will be triaging your incoming issue as soon as possible.

[stevebeauge]

From my experience: REST apis are poorly documented. There is no reference documentation for the API (only few articles to expose the general use of the apis).

Some tips I use to find information:

• REST api actually reflects most of the CSOM. For example, if you have a method like ListCollection.GetById, you can "transpose" it as a rest call _api/web/lists/getbyid('XXX'). It requires however to have a deep knowledge of SharePoint object model (in my example I know _api/web/lists matches Web.Lists which is of type ListCollection
• A very valuable resource to explore REST capacities is SharePoint REST API Metadata Explorer, written by Sergei Sergeev. This tool allows to explorer the REST types (based on Odata). If I take my previous example, you can discover
  • _api/web/ is of type SP.Web (click on it)
  • SP.Web contains a navigation property Lists which is of type Collection<Lists> (click on it)
  • Collection<Lists> contains a method named GetById (click on it)
  • GetById waits for a single argument id: Guid
• Few blog articles mention that OData can be less verbose by setting Accept and ContentType headers to application/json;odata=nometadata (if on Odata V3)

Once you understand this, you are not far to be able to navigate the documentation. The first result of your screenshot will contains what you are looking for. You'll just have to "transpose" it as web api.
You can navigate to GetByEmail which can be transposed to /_api/web/siteusers/getbyemail.

Not very satisfying but it allows to survive in the SP dev world

In opposition Graph API are a far better documentation, which payload samples and return. Maybe MS consider REST apis as legacy.

[omarelanis]

I feel your pain, and a lot of the knowledge is gained by others sharing it, but that's because SharePoint is a beast of a system which has grown massively over the years, as a result it has a number of different technology stacks which can be used to get the data you need, these include CSOM, JSOM, REST, CAML, KQL and the list goes on, as a result Microsoft in recent years has moved towards using the MS Graph API as a central point for all REST queries to any of it's services including SharePoint.

So you will be able to still find legacy information scattered around as you mentioned, but that's because the preferred route is now MS Graph.

One very good resource for most endpoint is PnP JS, it's an framework library which allows easy access to most REST endpoint and has some truly great documentation, if nothing else it'll help point you in the right direction a lot of the time!
https://pnp.github.io/pnpjs/

For example the following shows you the different endpoints for users as mentioned in your query:
https://pnp.github.io/pnpjs/sp/site-users/

To get you started with MS Graph take a look here:
https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0

Hope that helps :)

[github-actions]

Thank you for taking the time to file an issue. We periodically archive older or inactive issues as part of our issue management process, which automatically closes them once they are archived.

If you’d like to understand more about why and how we handle archived (closed) issues, please see Our approach to closed issues.

We appreciate your contribution and if this is still an active issue with the latest SPFx versions, please do resubmit the details. We needed to perform a cleanup, so that we can start with a clean table with a new process. We apologize for the inconvenience this might cause.