Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit 4f71292

Browse files
keharperkeharper
authored
fixed broken glossary links (#4964)
* fixed broken glossary links * fix broken link
1 parent 9e0a2ec commit 4f71292

File tree

3 files changed

+71
-66
lines changed

3 files changed

+71
-66
lines changed

‎guides/v2.2/extension-dev-guide/api-concepts.md

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,25 @@ menu_order: 3
88

99
## What is a public interface? {#public-interface}
1010

11-
<p>A <i>public interface</i> is a set of code that third-party developers can call, implement, or build as a [plug-in](https://glossary.magento.com/plug-in). Magento guarantees that this code will not change in subsequent releases without a major version change.</p>
12-
<p>Public interfaces for a [module](https://glossary.magento.com/module) are marked with <code>@api</code> annotation.</p>
11+
A _public interface_ is a set of code that third-party developers can call, implement, or build as a [plug-in](https://glossary.magento.com/plug-in). Magento guarantees that this code will not change in subsequent releases without a major version change.
12+
13+
Public interfaces for a [module](https://glossary.magento.com/module) are marked with `@api` annotation.
1314

1415
{: .bs-callout-info }
1516
Third-party developers should use only these interfaces, that is, interfaces with the `@api` annotation. You can use other interfaces but those may be modified or removed in subsequent Magento releases. For more information, see [Backward compatibility]({{ page.baseurl }}/contributor-guide/backward-compatible-development/).
1617

1718
## What is an API? {#api-definition}
1819

19-
<p>An application programming interface (API) is a set of interfaces and their implementations that a module provides to other modules.</p>
20+
An application programming interface (API) is a set of interfaces and their implementations that a module provides to other modules.
2021

2122
### API types {#api-types}
2223

23-
<p>The following items are considered types of APIs:</p>
24-
<ul>
25-
<li>Directory structure</li>
26-
<li>Configuration files structure</li>
27-
<li>Events</li>
28-
<li>Client API</li>
29-
<li>Provider [API](https://glossary.magento.com/api) (SPI)</li>
30-
</ul>
31-
<p>Directory structure and configuration file structure are types of APIs because [extension](https://glossary.magento.com/extension) developers use them. Developers write configurations, and place their [static files](https://glossary.magento.com/static-files) in specified folders; so if the configuration file structure or directory structure changes in subsequent releases, modules and extensions may break.</p>
24+
The following items are considered types of APIs:
25+
26+
- Directory structure
27+
- Configuration files structure
28+
- Events
29+
- Client API
30+
- Provider [API](https://glossary.magento.com/api) (SPI)
31+
32+
Directory structure and configuration file structure are types of APIs because [extension](https://glossary.magento.com/extension) developers use them. Developers write configurations, and place their [static files](https://glossary.magento.com/static-files) in specified folders; so if the configuration file structure or directory structure changes in subsequent releases, modules and extensions may break.

‎guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md

Lines changed: 43 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -6,59 +6,65 @@ menu_title: Service contract design patterns
66
menu_order: 4
77
---
88

9-
<p>In the programming community, a <i>design pattern</i> is a recommended way of writing code that includes when to use, or not use, the pattern. Think of a [design pattern](https://glossary.magento.com/design-pattern) as a best practice with conditions.</p>
10-
<p>Design patterns for service contracts tell you which types of interfaces to define, and how and where to define and implement those interfaces.</p>
9+
In the programming community, a _design pattern_ is a recommended way of writing code that includes when to use, or not use, the pattern. Think of a [design pattern](https://glossary.magento.com/design-pattern) as a best practice with conditions.
10+
11+
Design patterns for service contracts tell you which types of interfaces to define, and how and where to define and implement those interfaces.
1112

1213
{: .bs-callout-info }
1314
Service contract data interfaces are now mutable.
1415

1516
## Interface types and locations {#top-level-msc}
1617

17-
<p>A [service contract](https://glossary.magento.com/service-contract) must define data interfaces, which preserve data integrity, and service interfaces, which hide business logic from service requestors.</p>
18-
<p>Data interfaces define functions that return information about data entities, return search results, and set validation rules and return validation results. You must define the data interfaces for a service contract in the <b>Api/Data</b> subdirectory for a [module](https://glossary.magento.com/module).</p>
19-
<p>
20-
Service interfaces include management, repository, and [metadata](https://glossary.magento.com/metadata) interfaces.
21-
You must define the service interfaces for a service contract in the <b>Api</b> subdirectory for a module.<!-- You can substitute another implementation in this directory. -->
22-
</p>
18+
A [service contract](https://glossary.magento.com/service-contract) must define data interfaces, which preserve data integrity, and service interfaces, which hide business logic from service requestors.
19+
20+
Data interfaces define functions that return information about data entities, return search results, and set validation rules and return validation results. You must define the data interfaces for a service contract in the `Api/Data` subdirectory for a [module](https://glossary.magento.com/module).
21+
22+
Service interfaces include management, repository, and [metadata](https://glossary.magento.com/metadata) interfaces.
23+
You must define the service interfaces for a service contract in the `Api` subdirectory for a module.<!-- You can substitute another implementation in this directory. -->
24+
2325
<!--
2426
<p>For example, the interfaces in the <b>Magento\Customer\Api</b> [namespace](https://glossary.magento.com/namespace) define agreements, or a contract, between clients and implementations of services for the Magento Customer module.
2527
</p>
2628
-->
2729

2830
## Data interfaces {#data-interfaces}
2931

30-
<p>Define data interfaces in the <b>Api/Data</b> subdirectory for a module.</p>
31-
<p>For example, the data interfaces for the Customer module are in the <b>/app/code/Magento/Customer/Api/Data</b> subdirectory.</p>
32+
Define data interfaces in the `Api/Data` subdirectory for a module.
33+
34+
For example, the data interfaces for the Customer module are in the `/app/code/Magento/Customer/Api/Data` subdirectory.
3235

3336
### Data search results interfaces {#search-results-interfaces}
3437

35-
<p>When you pass search criteria to a <code>getList()</code> call, a search results interface is returned with the search results.</p>
36-
<p>You must define one interface for each data [entity](https://glossary.magento.com/entity) for type hinting purposes. That is, the <code>getItems()</code> function in the
37-
<code>CustomerSearchResultsInterface</code> returns an array of <code>CustomerInterface</code> data entities.
38-
In <code>GroupSearchResultsInterface</code>, the <code>getItems()</code> function returns an array of <code>GroupInterface</code> data entities.
39-
</p>
38+
When you pass search criteria to a `getList()` call, a search results interface is returned with the search results.
39+
40+
You must define one interface for each data [entity](https://glossary.magento.com/entity) for type hinting purposes. That is, the `getItems()` function in the
41+
`CustomerSearchResultsInterface` returns an array of `CustomerInterface` data entities.
42+
In `GroupSearchResultsInterface`, the `getItems()` function returns an array of `GroupInterface` data entities.
4043

4144
## Service interfaces {#service-interfaces}
4245

43-
<p>Service interfaces include several interface subtypes:</p>
44-
<ul>
45-
<li>Repository interfaces</li>
46-
<li>Management interfaces</li>
47-
<li>Metadata interfaces</li>
48-
</ul>
49-
<p>For file names and coding standards, follow the defined <a href="{{ page.baseurl }}/coding-standards/code-standard-php.html">PHP coding standards</a>.</p>
50-
<p>Place service interfaces in the top-level <b>Api</b> directory for a module.</p>
46+
Service interfaces include several interface subtypes:
47+
48+
- Repository interfaces
49+
- Management interfaces
50+
- Metadata interfaces
51+
52+
For file names and coding standards, follow the defined [PHP coding standards]({{ page.baseurl }}/coding-standards/code-standard-php.html).
53+
54+
Place service interfaces in the top-level `Api` directory for a module.
5155

5256
### Repository interfaces {#repository-interfaces}
5357

54-
<p>Repository interfaces provide access to persistent data entities.</p>
55-
<p>For example, persistent data entities for the Customer module include Customer, Address, and Group. Consequently, repository interfaces for the Customer module are:</p>
56-
<ul>
57-
<li><code>CustomerRepositoryInterface</code></li>
58-
<li><code>AddressRepositoryInterface</code></li>
59-
<li><code>GroupRepositoryInterface</code></li>
60-
</ul>
61-
<p>Repository interfaces must provide these functions:</p>
58+
Repository interfaces provide access to persistent data entities.
59+
60+
For example, persistent data entities for the Customer module include Customer, Address, and Group. Consequently, repository interfaces for the Customer module are:
61+
62+
- `CustomerRepositoryInterface`
63+
- `AddressRepositoryInterface`
64+
- `GroupRepositoryInterface`
65+
66+
Repository interfaces must provide these functions:
67+
6268
<table style="width:100%">
6369
<tr bgcolor="lightgray">
6470
<th>Function</th>
@@ -108,11 +114,13 @@ Service contract data interfaces are now mutable.
108114
</td>
109115
</tr>
110116
</table>
111-
<p>Each data entity has a corresponding interface. Consequently, the <code>get()</code> function in the corresponding interface, for example, can return the exact type.</p>
117+
118+
Each data entity has a corresponding interface. Consequently, the `get()` function in the corresponding interface, for example, can return the exact type.
112119

113120
### Management interfaces {#management-interfaces}
114121

115-
<p>Management interfaces provide management functions that are not related to repositories. For example:</p>
122+
Management interfaces provide management functions that are not related to repositories. For example:
123+
116124
<table style="width:100%">
117125
<tr bgcolor="lightgray">
118126
<th>Interface</th>
@@ -138,8 +146,5 @@ Service contract data interfaces are now mutable.
138146

139147
### Related topics {#related-topics}
140148

141-
<ul>
142-
<li><a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-contracts.html">Service contracts</a></li>
143-
<li><a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html">Configure services as web APIs</a>
144-
</li>
145-
</ul>
149+
- [Service contracts]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-contracts.html)
150+
- [Configure services as web APIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html)

‎guides/v2.2/extension-dev-guide/service-contracts/service-contracts.md

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,30 +16,29 @@ To address these issues, the Magento system introduces _service contracts_.
1616

1717
## What is a service contract? {#what-is-msc}
1818

19-
<p>A [service contract](https://glossary.magento.com/service-contract) is a set of [PHP](https://glossary.magento.com/php) interfaces that are defined for a [module](https://glossary.magento.com/module).
20-
A service contract includes <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#data-interfaces">data interfaces</a>, which preserve data integrity, and <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#service-interfaces">service interfaces</a>, which hide business logic details from service requestors such as controllers, web services, and other modules.
21-
</p>
22-
<p>If developers define data and service interfaces according to a set of <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html">design patterns</a>, the result is a well-defined, durable [API](https://glossary.magento.com/api) that other modules and third-party extensions can implement through Magento models and resource models.
23-
</p>
24-
<p><img src="{{ site.baseurl }}/common/images/msc.jpg"/></p>
19+
A [service contract](https://glossary.magento.com/service-contract) is a set of [PHP](https://glossary.magento.com/php) interfaces that are defined for a [module](https://glossary.magento.com/module).
20+
A service contract includes [data interfaces]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#data-interfaces), which preserve data integrity, and [service interfaces]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html#service-interfaces), which hide business logic details from service requestors such as controllers, web services, and other modules.
21+
22+
If developers define data and service interfaces according to a set of [design patterns]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html), the result is a well-defined, durable [API](https://glossary.magento.com/api) that other modules and third-party extensions can implement through Magento models and resource models.
23+
24+
![Service Contracts]({{ site.baseurl }}/common/images/msc.jpg)
2525

2626
## Service contract benefits {#msc-benefits}
2727

28-
<p>Service contracts enhance the modularity of Magento. They enable Magento and third-party developers to report system dependencies through <b>composer.json</b> files and, consequently, guarantee compatibility among Magento versions. This compatibility ensures that merchants can easily upgrade Magento.</p>
29-
<p>These contracts ensure a well-defined, durable API that other modules and third-party extensions can implement. Also, these contracts make it easy to <a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html">configure services as web APIs</a>.
30-
</p>
31-
<p>Data entities are a side benefit of service contracts.
32-
The database tables that normally support these entities can be complicated.
33-
For example, some attributes might be stored in an EAV table, so a set of MySQL database tables might define a single data [entity](https://glossary.magento.com/entity).
34-
Data entities in a service contract reveal a simpler data model than the data model in an underlying relational [database schema](https://glossary.magento.com/database-schema).
35-
Eventually, you will be able to use different storage technologies for different data collections. For example, you could use a NoSQL database to replace product tables.
36-
</p>
28+
Service contracts enhance the modularity of Magento. They enable Magento and third-party developers to report system dependencies through `composer.json` files and, consequently, guarantee compatibility among Magento versions. This compatibility ensures that merchants can easily upgrade Magento.
29+
These contracts ensure a well-defined, durable API that other modules and third-party extensions can implement. Also, these contracts make it easy to [configure services as web APIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html).
30+
31+
Data entities are a side benefit of service contracts.
32+
The database tables that normally support these entities can be complicated.
33+
For example, some attributes might be stored in an EAV table, so a set of MySQL database tables might define a single data [entity](https://glossary.magento.com/entity).
34+
Data entities in a service contract reveal a simpler data model than the data model in an underlying relational [database schema](https://glossary.magento.com/database-schema).
35+
Eventually, you will be able to use different storage technologies for different data collections. For example, you could use a NoSQL database to replace product tables.
3736

3837
## Using the @api tag
3938

4039
Backward compatibility can be indicated by the use of `@api`. For more information, see [Backward compatibility]({{ page.baseurl }}/contributor-guide/backward-compatible-development/).
4140

4241
### Related topics {#related-topics}
4342

44-
- [Service contract designpatterns]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html)
43+
- [Service contract design patterns]({{ page.baseurl }}/extension-dev-guide/service-contracts/design-patterns.html)
4544
- [Configure services as webAPIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html)

0 commit comments

Comments
 (0)