This task provides examples of basic workflows for the API Portal.
To do: Review with stakeholders and finalize
#### Anonymous requests (No OAuth flow)
* Read-only
* For evaluation and prototyping
* Anonymous requests have a lower rate limit than requests that use an OAuth flow.
```
# Read requests
GET https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth
# Write requests
Returns a TBD error# Without OAuth or a csrf token, Core REST API returns a 400 error
{
"actionModuleErrorCode": "missingparam",
"messageTranslations": {
"en": "The \"token\" parameter must be set."
},
"httpCode": 400,
"httpReason": "Bad Request"
}
```
#### OAuth 2.0: App authorization (client-credentials workflow, two-legged)
* For use by apps without a user authorization flow, effectively providing anonymous access for the user while including a client ID to support rate limiting.
* Developer creates an OAuth 2.0 client with "authorization_code", "refresh_token", and "client_credentials" as the grant types.
* Client does not require manual approval.
```
# Get access token
POST https://meta.wikimedia.org/w/rest.php/oauth/access_token?grant_type=client_credentials&client_id=<client id>&client_secret=<client secret>
# Call API on behalf of app
GET https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth
Authorization: Bearer <access-token>
```
#### OAuth 2.0: User authorization (authorization-code workflow, three-legged)
* For use by apps that make requests on behalf of a user.
* Developer creates an OAuth 2.0 client with "authorization_code", "refresh_token", and "client_credentials" as the grant types.
* Client does not require manual approval to be authorized by the owner's account.
* Client requires manual approval (via a request to [Meta](https://meta.wikimedia.org/wiki/Steward_requests/Miscellaneous)) to be authorized by other users.
```
# Request authorization from user
https://meta.wikimedia.org/w/rest.php/oauth/authorize?client_id=<client id>&response_type=code
# Get access token
POST https://meta.wikimedia.org/w/rest.php/oauth/access_token?grant_type=authorization_code&code=<authorization code>&client_id=<client id>&client_secret=<client secret>&redirect_uri=<return URL>
# Call API on behalf of user
GET https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth
Authorization: Bearer <access-token>
# Get refresh token
POST https://meta.wikimedia.org/w/rest.php/oauth/access_token?grant_type=refresh_token&refresh_token=<refresh token>
```
#### OAuth 2.0: Owner authorization (access-token-only workflow, single-legged)
* For use by bot accounts.
* Developer logs in to the API Portal with their local-wiki-approved bot account and creates an OAuth 2.0 client with the “This consumer is for use only by [Username]” option applied.
* Client does not require manual approval.
```
# Call API on behalf of client owner
GET https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth
Authorization: Bearer <access-token>
```
#### References
* https://www.mediawiki.org/wiki/API:Tokens
* [[https://docs.google.com/document/d/1qe3Z3rvCyO_EfDT4QzE_DCCa0C4_MNKI-5fDkdbGyFg/edit?ts=5e1e192d# | URL mappings doc]]
* https://www.mediawiki.org/wiki/OAuth/For_Developers#OAuth_2
* https://www.mediawiki.org/wiki/API:REST_API/Pages