Clarify API concepts (MetaMask#906)

* Clarify API concepts

* delete old file

* minor link fixes

* remove web3

docusaurus.config.js

@@ -284,6 +284,14 @@ const config = {
             from: "/wallet/how-to/set-icon",
             to: "/wallet/how-to/display/icon",
           },
+          {
+            from: "/wallet/concepts/provider-api",
+            to: "/wallet/concepts/apis",
+          },
+          {
+            from: "/wallet/concepts/rpc-api",
+            to: "/wallet/concepts/apis",
+          },
         ].reduce((acc, item) => {
           acc.push(item);
           acc.push({ from: item.from + ".html", to: item.to });

wallet/concepts/apis.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 3
+description: Learn about the MetaMask Ethereum provider API.
+---
+
+# What are the MetaMask APIs?
+
+MetaMask supports an [Ethereum provider API](#ethereum-provider-api), which wraps a [JSON-RPC API](#json-rpc-api).
+
+:::tip API documentation
+The API methods are documented in the following references:
+
+- [Ethereum provider API reference](../reference/provider-api.md)
+- [JSON-RPC API playground](/wallet/reference/eth_subscribe)
+:::
+
+## Ethereum provider API
+
+MetaMask injects a global JavaScript API into websites visited by its users using the
+`window.ethereum` provider object.
+This API is specified by [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193), and it allows dapps to
+request users' Ethereum accounts, read data from blockchains the user is connected to, suggest
+that the user sign messages and transactions, and more.
+
+The MetaMask Ethereum provider API contains the following:
+
+- [Properties](../reference/provider-api.md#properties) - The provider contains a property that
+  detects if a user has MetaMask installed.
+- [Methods](../reference/provider-api.md#methods) - The provider contains methods that dapps can call.
+  The [`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs)
+  provider method wraps the [JSON-RPC API](#json-rpc-api); dapps can use this
+  provider method to call any RPC method.
+- [Events](../reference/provider-api.md#events) - The provider emits events that dapps can listen to.
+
+View the [provider API reference](../reference/provider-api.md) for all the provider properties,
+methods, and events.
+
+:::tip Use MetaMask SDK with the provider API
+You can call the provider API from a dapp with or without [MetaMask SDK](sdk.md) installed, but we
+recommend using the SDK to enable users to easily connect to the MetaMask browser extension and
+MetaMask Mobile.
+The SDK supports multiple dapp platforms including mobile and gaming dapps.
+
+Get started by [setting up the SDK](../how-to/connect/set-up-sdk/index.md).
+:::
+
+## JSON-RPC API
+
+MetaMask uses the [`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs)
+method of the [provider API](#ethereum-provider-api) to wrap a JSON-RPC API.
+The JSON-RPC API contains standard Ethereum JSON-RPC API methods and MetaMask-specific methods.
+
+The RPC methods are documented in the interactive
+[JSON-RPC API playground](/wallet/reference/eth_subscribe).
+Methods in the API playground may have the following tags:
+
+- **MetaMask** - These methods behave in ways specific to MetaMask, and may or may not be supported
+  by other wallets.
+- **Restricted** - These methods are [restricted](#restricted-methods), which require requesting
+  permission using [`wallet_requestPermissions`](/wallet/reference/wallet_requestpermissions).
+- **Mobile** - These methods are only available on MetaMask Mobile.
+- **Ethereum API** - These are standard Ethereum JSON-RPC API methods.
+  See the [Ethereum wiki](https://eth.wiki/json-rpc/API#json-rpc-methods) for more information on
+  these methods.
+
+:::note
+All RPC method requests can return errors.
+Make sure to handle errors for every call to
+[`window.ethereum.request(args)`](../reference/provider-api.md#windowethereumrequestargs).
+:::
+
+### Restricted methods
+
+MetaMask introduced wallet permissions in [EIP-2255](https://eips.ethereum.org/EIPS/eip-2255).
+In this permissions system, each RPC method is restricted or unrestricted.
+If a method is restricted, a dapp must request permission to call it using
+[`wallet_requestPermissions`](/wallet/reference/wallet_requestpermissions).
+Under the hood, permissions are plain, JSON-compatible objects, with fields that are mostly used
+internally by MetaMask.
+
+Outside of [Snaps restricted methods](/snaps/reference/rpc-api/#restricted-methods), the only
+restricted method is [`eth_accounts`](/wallet/reference/eth_accounts), which allows you to access
+the user's Ethereum accounts.
+More restricted methods will be added in the future.
+
+### Unrestricted methods
+
+Unrestricted methods do not require requesting permission to call them, but they might still rely on
+permissions to succeed (for example, the signing methods require calling the restricted
+[`eth_accounts`](/wallet/reference/eth_accounts) method), or they might require confirmation by the
+user (for example, [`wallet_addEthereumChain`](/wallet/reference/wallet_addethereumchain)).

wallet/concepts/architecture.md

@@ -11,6 +11,6 @@ The following diagram outlines the high-level architecture of the MetaMask web3
 
 Using [MetaMask SDK](sdk.md), dapps built on multiple platforms can connect to their users' Ethereum
 accounts through the MetaMask browser extension and MetaMask Mobile.
-Dapps can send [JSON-RPC API](../reference/rpc-api.md) calls to the users' MetaMask wallet clients.
+Dapps can send [JSON-RPC API](apis.md#json-rpc-api) calls to the users' MetaMask wallet clients.
 MetaMask then responds to these requests directly or uses [Infura](https://www.infura.io/) (or
 another user-configured node provider) when the call requires access to information on a blockchain network.

wallet/concepts/convenience-libraries.md

@@ -1,6 +1,6 @@
 ---
 description: Learn about convenience libraries.
-sidebar_position: 5
+sidebar_position: 4
 ---
 
 # Convenience libraries

wallet/concepts/sdk.md

@@ -3,11 +3,11 @@ description: Learn about MetaMask SDK.
 sidebar_position: 2
 ---
 
-# MetaMask SDK
+# What is MetaMask SDK?
 
 MetaMask SDK is a library that provides a reliable, secure, and seamless connection from your dapp
 to the MetaMask browser extension and MetaMask Mobile.
-You can install the SDK in existing dapps, and call any [provider API](provider-api.md) methods from
+You can install the SDK in existing dapps, and call any [provider API](apis.md) methods from
 your dapp.
 
 :::tip Get started

wallet/concepts/signing-methods.md

@@ -1,6 +1,6 @@
 ---
 description: Learn about the RPC methods for signing transactions in MetaMask.
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 # Signing methods

wallet/how-to/connect/access-accounts.md

@@ -9,7 +9,7 @@ User accounts are used in a variety of contexts in Ethereum, including as identi
 [signing transactions](../sign-data/index.md).
 To request a signature from a user or have a user approve a transaction, your dapp must
 access the user's accounts using the
-[`eth_requestAccounts`](../../reference/rpc-api.md#eth_requestaccounts) RPC method.
+[`eth_requestAccounts`](/wallet/reference/eth_requestaccounts) RPC method.
 
 When accessing a user's accounts:
 

wallet/how-to/interact-with-smart-contracts.md

@@ -20,8 +20,8 @@ Many dapp developers deploy their contract to a testnet first, in order to avoid
 disastrous fees if something goes wrong during development and testing on Mainnet.
 
 Regardless of which network you deploy your final dapp on, your users must be able to access it.
-Use the [`wallet_switchEthereumChain`](../reference/rpc-api.md#wallet_switchethereumchain) and
-[`wallet_addEthereumChain`](../reference/rpc-api.md#wallet_addethereumchain) RPC methods to prompt
+Use the [`wallet_switchEthereumChain`](/wallet/reference/wallet_switchethereumchain) and
+[`wallet_addEthereumChain`](/wallet/reference/wallet_addethereumchain) RPC methods to prompt
 the user to add a chain that you suggest, and switch to it using a confirmation dialogue.
 
 ## Contract address

wallet/index.md

@@ -17,7 +17,7 @@ You can enable users to connect to their MetaMask wallets from the following dap
 [MetaMask SDK](concepts/sdk.md) is a library that provides a reliable, secure, and seamless
 connection from your dapp to the MetaMask browser extension and MetaMask Mobile.
 
-With the SDK installed, your dapp can use the [MetaMask Ethereum provider API](concepts/provider-api.md)
+With the SDK installed, your dapp can use the [MetaMask Ethereum provider API](concepts/apis.md)
 to request users' Ethereum accounts, read data from blockchains the user is connected to, suggest
 that the user sign messages and transactions, and more.
 :::

wallet/reference/provider-api.md

@@ -5,8 +5,8 @@ sidebar_position: 2
 
 # Ethereum provider API
 
-MetaMask injects the [provider API](../concepts/provider-api.md) into websites visited by its users
-using the `window.ethereum` provider object.
+MetaMask injects the [provider API](../concepts/apis.md#ethereum-provider-api) into websites visited
+by its users using the `window.ethereum` provider object.
 You can use the provider [properties](#properties), [methods](#methods), and [events](#events) in
 your dapp.
 

wallet/reference/rpc-api.md

@@ -7,7 +7,7 @@ toc_max_heading_level: 2
 # JSON-RPC API
 
 MetaMask uses the [`window.ethereum.request(args)`](provider-api.md#windowethereumrequestargs)
-provider method to wrap a [JSON-RPC API](../concepts/rpc-api.md).
+provider method to wrap a [JSON-RPC API](../concepts/apis.md#json-rpc-api).
 The API contains standard Ethereum JSON-RPC API methods and MetaMask-specific methods.
 
 :::tip MetaMask API playground
@@ -18,7 +18,7 @@ The RPC methods are documented in the interactive
 For more information on the standard Ethereum RPC methods, see the
 [Ethereum wiki](https://eth.wiki/json-rpc/API#json-rpc-methods).
 
-The following are some MetaMask-specific [unrestricted methods](../concepts/rpc-api.md#unrestricted-methods).
+The following are some MetaMask-specific [unrestricted methods](../concepts/apis.md#unrestricted-methods).
 For the full list of MetaMask JSON-RPC API methods, see the
 [API playground](/wallet/reference/eth_subscribe).