-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlearn_models.md.CcyHn3IU.js
25 lines (25 loc) · 14.3 KB
/
learn_models.md.CcyHn3IU.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import{_ as s,c as e,o as a,a9 as i}from"./chunks/framework.DgZLXPSQ.js";const g=JSON.parse('{"title":"What does a Model mean?","description":"","frontmatter":{},"headers":[],"relativePath":"learn/models.md","filePath":"learn/models.md"}'),t={name:"learn/models.md"},n=i(`<h1 id="what-does-a-model-mean" tabindex="-1">What does a Model mean? <a class="header-anchor" href="#what-does-a-model-mean" aria-label="Permalink to "What does a Model mean?""></a></h1><p class="description"> In this chapter, we'll explore the magic of Axe API models. These powerful features simplify and accelerate API development, allowing developers to define the structure and behavior of their APIs quickly and easily. </p><ul class="intro"><li>You will learn</li><li>What does a Model mean?</li><li>How does Axe API handle models?</li><li>How to configure an Axe API model?</li><li>How to add your custom logic?</li></ul><h2 id="fundamentals" tabindex="-1">Fundamentals <a class="header-anchor" href="#fundamentals" aria-label="Permalink to "Fundamentals""></a></h2><p>Axe API models are a magical feature that can simplify and accelerate the development of robust and customizable APIs.</p><p>Unlike traditional <strong>ORM models</strong>, Axe API models offer a flexible and powerful way to define the structure and behavior of your API, without requiring developers to write complex and time-consuming code.</p><p>By defining a model, developers can specify how data should be stored, retrieved, updated, and deleted. When a model is saved, Axe API analyzes it and <strong><em>creates routes automatically</em></strong> based on the model's structure and configuration.</p><p>This means that developers can focus on building their API's business logic rather than worrying about the low-level details of handling requests and responses.</p><h2 id="basic-model-example" tabindex="-1">Basic model example <a class="header-anchor" href="#basic-model-example" aria-label="Permalink to "Basic model example""></a></h2><p>To illustrate the magic of Axe API models, consider the following example:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { Model } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "axe-api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> User</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> extends</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> User;</span></span></code></pre></div><p>This simple model generates routes for CRUD (<em>Create, Read, Update, Delete</em>) operations on users automatically, without requiring any additional code.</p><p>Specifically, the following routes are created:</p><ul><li><code>GET api/v1/users</code>: Retrieve a paginated list of all users</li><li><code>POST api/v1/users</code>: Create a new user</li><li><code>GET api/v1/users/:id</code>: Retrieve a user by ID</li><li><code>PUT api/v1/users/:id</code>: Update a user by ID</li><li><code>DELETE api/v1/users/:id</code>: Delete a user by ID</li></ul><p>By default, Axe API generates routes for CRUD operations based on the structure of the model. However, developers can customize the routes by adding additional configurations, which makes Axe API models even more powerful.</p><p>Overall, the magic of Axe API models lies in their ability to simplify and automate the development of APIs, allowing developers to focus on building the core logic of their application.</p><p>With Axe API models, developers can create robust and customizable APIs in less time and with less effort than ever before.</p><h2 id="how-to-configure-a-model" tabindex="-1">How to configure a model? <a class="header-anchor" href="#how-to-configure-a-model" aria-label="Permalink to "How to configure a model?""></a></h2><p>Axe API's model configurations provide a <strong><em>declarative way</em></strong> to define the behavior of your API.</p><p>In the example below, we have defined the <code>Users</code> model and set the <code>fillable</code> property to include only the <code>name</code> and <code>surname</code> fields. This means that any data sent by HTTP clients with additional fields will be automatically discarded by the API, except the <code>name</code> and <code>surname</code> fields.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { Model } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "axe-api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">class</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Users</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> extends</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> get</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fillable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"name"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"surname"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">];</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> get</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> validations</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"required|max:50"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> surname: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"required|max:50"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> User;</span></span></code></pre></div><p>We have also defined data validation rules using the <code>validations</code> property. This ensures that any data sent by HTTP clients must meet the defined rules before it is accepted and processed by the API. This prevents the API from processing invalid data and <strong>guarantees</strong> that all responses are <strong>consistent</strong>.</p><p>One of the great advantages of using Axe API models is that you no longer need traditional <strong>Controller</strong> files. Axe API handles all the requests automatically based on your models, making development faster and more efficient.</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>It's worth noting that all model configurations are <code>getters</code>.</p><p>In the future, this will allow developers to define model configurations in <code>YAML</code> or <code>JSON</code> formats, making the API even easier to configure and maintain.</p></div><p>Overall, Axe API model configurations are a powerful and flexible way to define the behavior of your API. With a little bit of configuration, you can ensure that your API works as you want, without the need for complex controllers.</p><h2 id="customize-logic" tabindex="-1">Customize logic <a class="header-anchor" href="#customize-logic" aria-label="Permalink to "Customize logic""></a></h2><p>As you can see, Axe API creates and handles your API automatically. But it may not be enough for most scenarios. As developers, we should be able to add custom logic to our APIs.</p><p>Axe API allows developers to add custom logic in many different ways. We will discuss each method in the following sections. However, here we will summarize the basic understanding.</p><p>Axe API uses <strong>events</strong> for every HTTP action, such as <em>before inserting data</em>, <em>after inserting data</em>, <em>before paginating</em>, <em>after paginating</em>, etc. For every HTTP request handling process, there are many <strong>events</strong> that developers can use in their code.</p><p>Axe API has two different categories of <strong>events</strong> by their <code>async</code>/<code>sync</code> status: <code>hooks</code> and <code>events</code>.</p><p>Hooks work as <strong>synchronous</strong> with the HTTP requests, but events work <strong>asynchronously</strong>.</p><p>Let's take a look at the following example. In the following function, the <code>password</code> field is hashed using the <code>bcrypt</code> library:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> bcrypt </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "bcrypt"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { IContext } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "axe-api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">formData</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> IContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> formData.password </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> bcrypt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">hashSync</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(formData.password, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">10</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><p>If you save this file as <code>app/v1/Hooks/User/onBeforeInsert.ts</code> in your codebase, Axe API will execute your <strong>hook function</strong> before inserting a new record on <code>users</code> table via <code>User</code> model.</p><p>Using this method, you can add any custom logic to your API <strong>request life-cycle</strong>. For example, you can add validation rules or enrich the request data by integrating with external services.</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Also, hook and event functions are independent functions that can be tested easily via unit tests.</p></div><h2 id="next-step" tabindex="-1">Next step <a class="header-anchor" href="#next-step" aria-label="Permalink to "Next step""></a></h2><p>In this section, we tried to understand the fundamentals of Axe API models. In this next chapter, we will think about how to manage your API routes by using model definitions.</p>`,38),l=[n];function o(h,r,d,p,c,k){return a(),e("div",null,l)}const m=s(t,[["render",o]]);export{g as __pageData,m as default};