docs: Add REST endpoints documentation #13
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
justlevine
requested changes
Oct 5, 2024
justlevine
requested changes
Oct 9, 2024
- Remove unnecessary elements - Check & verify everything is accurate.
justlevine
reviewed
Oct 15, 2024
docs/rest-api.md
Outdated
Comment on lines
35
to
75
| ### Testing Instructions | ||
|
|
||
| To verify the functionality of this endpoint, you can use any API testing tool (e.g., cURL, Postman, or a custom script). Follow these steps: | ||
|
|
||
| 1. **Set up the request**: | ||
| * Create a new GET request. | ||
| * Set the URL to: `https://your-wordpress-site.com/wp-json/snapwp/v1/env` | ||
|
|
||
| 2. **Set up Authentication**: | ||
| * Use Basic Auth with your WordPress username and the application password you generated. | ||
|
|
||
| 3. **Set up Request Body**: | ||
| * In the "Body" tab, select "raw" and choose "JSON" from the dropdown. | ||
| * In the request body, enter the following JSON: | ||
| ```json | ||
| { | ||
| "variables": [ | ||
| { | ||
| "name": "NEXT_URL", | ||
| "value": "http://localhost:3000" | ||
| }, | ||
| { | ||
| "name": "HOME_URL", | ||
| "value": "https://headless-demo.local" | ||
| }, | ||
| { | ||
| "name": "GRAPHQL_ENDPOINT", | ||
| "value": "wp-graphql" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| 4. **Send the Request and Verify Responses**: | ||
| * Send the request and verify that you receive a 200 OK response. | ||
| * Check that the response body matches the example in the documentation. | ||
|
|
||
| 5. **Test Error Cases**: | ||
| * Remove all variables from the request body and send the request. Verify that you receive a 400 Bad Request response matching the documentation. | ||
| * Remove one of the required variables (e.g., NEXT_URL) and send the request. Verify that you receive a 500 Internal Server Error response matching the documentation. | ||
|
|
There was a problem hiding this comment.
Again, these are usage docs for developers. Teaching readers how to use REST is beyond the scope. Please remove.
There was a problem hiding this comment.
Removed this and added an example curl request.
justlevine
reviewed
Oct 15, 2024
docs/rest-api.md
Outdated
Comment on lines
24
to
33
| ### Authentication | ||
|
|
||
| This endpoint requires administrator privileges. To authenticate: | ||
|
|
||
| 1. In your WordPress admin panel, go to Users -> Your Profile. | ||
| 2. Scroll down to the "Application Passwords" section. | ||
| 3. Enter a name for your application password (e.g., "API Testing") and click "Add New Application Password". | ||
| 4. Copy the generated password. | ||
|
|
||
| You'll use this password along with your username for Basic Auth when making requests. |
justlevine
requested changes
Oct 15, 2024
justlevine
approved these changes
Oct 15, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
This PR adds comprehensive documentation for the REST API endpoint (
snapwp/v1/env) used in the SnapWP Helper plugin.Why
Documentation is crucial for developers who want to integrate with or extend our plugin. This PR addresses the lack of detailed REST API documentation, making it easier for developers to understand and use our endpoint.
Related Issue(s):
How
docs/rest-api.mdfile with detailed documentation for thesnapwp/v1/envendpoint.README.mdfile to include a link to the new REST API documentation.The documentation covers:
Testing Instructions
docs/rest-api.mdfile to ensure all information is accurate and complete.README.mdfile to confirm the new link to the REST API documentation is present and correct.Screenshots
N/A (Documentation changes only)
Additional Info
N/A
Checklist