AP-API-Register #22
AP-API-Register #22
Conversation
caidobot
temporarily deployed
to
AP-API-Register - doc-developer PR #22
Render
Destroyed
|
Images automagically compressed by Calibre's image-actions ✨ Compression reduced images by 38.5%, saving 16.65 KB.
13 images did not require optimisation. |
|
|
src/guides/components/endpoint.md
Outdated
| # Creating a Custom Endpoint | ||
|
|
||
| When developing a plugin, there are two components to consider: the **frontend** and the **backend**. | ||
|
|
||
| You can conceptualize the difference between these two components in the context of operating a car. | ||
|
|
||
| The frontend includes all the buttons, dials, pedals, and other controls available to you as the driver. Some components, such as sun visors and the rear-view mirror, are purely frontend. However, most frontend components communicate with the "under-the-hood" backend. This relationship is what allows actions like pressing the gas pedal to accelerate the engine - or, in the context of Caido; clicking a button to send a request. | ||
|
|
||
| ## Frontend | ||
|
|
||
| A "_page_" in Caido simply refers to a user interface. For example, the [Replay](https://docs.caido.io/reference/features/testing/replay.html) and [Automate](https://docs.caido.io/reference/features/testing/automate.html) side menu tabs each produce their own page. | ||
|
|
||
| Within these pages are components and elements specific to the feature, such as option menus and buttons. It is through these components and elements that the appearance is customized or communication with the backend occurs. | ||
|
|
||
| Think of the Caido application as a browser window with multiple open tabs, each corresponding to a specific page. | ||
|
|
||
| ## Backend | ||
|
|
||
| The backend refers to what is available server-side, what is "_under-the-hood_" or "_out-of-sight_". By incorporating a backend aspect to your plugin, you can extend upon the server-side functionality. This includes storing the data produced by your plugin, sending HTTP requests, or processing user-supplied data. |
There was a problem hiding this comment.
We should move some of this to https://developer.caido.io/concepts/essentials/package.html
Guides are meant to help users who just need a step-by-step on how to solve a specific problem. Users might come back to this often, but don't necessarily need the explanations on backend vs frontend every time.
So I would boil this section down into something like:
"In this guide, we'll cover how to create a custom endpoint in a backend plugin, and call it from a frontend plugin.
For more information on the differences between a frontend and backend plugin, take a look at our Plugin Architecture
"
src/guides/components/endpoint.md
Outdated
|
|
||
| The backend refers to what is available server-side, what is "_under-the-hood_" or "_out-of-sight_". By incorporating a backend aspect to your plugin, you can extend upon the server-side functionality. This includes storing the data produced by your plugin, sending HTTP requests, or processing user-supplied data. | ||
|
|
||
| ## sdk.api.register() |
There was a problem hiding this comment.
Let's use titles that describe the sequence of operations that a user has to do. https://diataxis.fr/how-to-guides/#describe-a-logical-sequence
So the outline for the guide would be something like
- Registering an API Endpoint
- Calling the API Endpoint
sdk.api.register() is just one of many functions that needs to be used in order to register an endpoint. No need to give it its own title.
src/guides/components/endpoint.md
Outdated
| ``` ts | ||
| import { SDK, DefineAPI } from "caido:plugin"; | ||
|
|
||
| function multiply(sdk: SDK, a: number, b: number) { | ||
| const result = a * b; | ||
| sdk.console.log(`The product of the multiply call is: ${result}`); | ||
| return result; | ||
| } | ||
|
|
||
| export type API = DefineAPI<{ | ||
| multiply: typeof multiply; | ||
| }>; | ||
|
|
||
| export function init(sdk: SDK<API>) { | ||
| sdk.api.register("multiply", multiply); | ||
| } | ||
| ``` | ||
|
|
||
| </details> | ||
| ::: |
There was a problem hiding this comment.
I would avoid having code snippets that need to be expanded. If anything, this snippet is the most relevant part for the user, cause they can just copy paste the entire thing and update it as needed.
Can we try having that snippet near the top of the "Registering an API Endpoint" section (no need to wrap it in a :::tip:::), then have the explanations for each part underneath?
src/guides/components/endpoint.md
Outdated
| } | ||
| ``` | ||
|
|
||
| ::: tip |
There was a problem hiding this comment.
Same comment regarding code snippets that need to be expanded. Let's bring that to the top of the section.
src/guides/components/endpoint.md
Outdated
|
|
||
| --- | ||
|
|
||
| <img alt="Calling the API." src="/_images/api_register_function.png" center/> |
There was a problem hiding this comment.
I think this is a good screenshot to show at the end of the article.
The outline of the article ends up being:
- "Here's what we're gonna do"
- "Here's how to do it"
- "Here's what the final result looks like"
caidobot
temporarily deployed
to
AP-API-Register - doc-developer PR #22
Render
Destroyed
No description provided.