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

fixed broken glossary links #4964

Merged
merged 5 commits into from
Jul 16, 2019
Merged

fixed broken glossary links #4964

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4040e88
fixed broken glossary links
keharper Jul 15, 2019
3ae6451
Merge branch 'master' into kh_fix-glossary-links
keharper Jul 15, 2019
ad2d83f
fix broken link
keharper Jul 16, 2019
ae715d9
Merge branch 'master' of github.com:magento/devdocs into kh_fix-gloss…
keharper Jul 16, 2019
f9dad55
Merge branch 'kh_fix-glossary-links' of github.com:magento/devdocs in…
keharper Jul 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions guides/v2.2/extension-dev-guide/api-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,24 +8,25 @@ menu_order: 3

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

<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>
<p>Public interfaces for a [module](https://glossary.magento.com/module) are marked with <code>@api</code> annotation.</p>
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.

Public interfaces for a [module](https://glossary.magento.com/module) are marked with `@api` annotation.

{: .bs-callout-info }
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/).

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

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

### API types {#api-types}

<p>The following items are considered types of APIs:</p>
<ul>
<li>Directory structure</li>
<li>Configuration files structure</li>
<li>Events</li>
<li>Client API</li>
<li>Provider [API](https://glossary.magento.com/api) (SPI)</li>
</ul>
<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>
The following items are considered types of APIs:

- Directory structure
- Configuration files structure
- Events
- Client API
- Provider [API](https://glossary.magento.com/api) (SPI)

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.
81 changes: 43 additions & 38 deletions guides/v2.2/extension-dev-guide/service-contracts/design-patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,59 +6,65 @@ menu_title: Service contract design patterns
menu_order: 4
---

<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>
<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>
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.

Design patterns for service contracts tell you which types of interfaces to define, and how and where to define and implement those interfaces.

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

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

<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>
<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>
<p>
Service interfaces include management, repository, and [metadata](https://glossary.magento.com/metadata) interfaces.
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. -->
</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.

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).

Service interfaces include management, repository, and [metadata](https://glossary.magento.com/metadata) interfaces.
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. -->

<!--
<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.
</p>
-->

## Data interfaces {#data-interfaces}

<p>Define data interfaces in the <b>Api/Data</b> subdirectory for a module.</p>
<p>For example, the data interfaces for the Customer module are in the <b>/app/code/Magento/Customer/Api/Data</b> subdirectory.</p>
Define data interfaces in the `Api/Data` subdirectory for a module.

For example, the data interfaces for the Customer module are in the `/app/code/Magento/Customer/Api/Data` subdirectory.

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

<p>When you pass search criteria to a <code>getList()</code> call, a search results interface is returned with the search results.</p>
<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
<code>CustomerSearchResultsInterface</code> returns an array of <code>CustomerInterface</code> data entities.
In <code>GroupSearchResultsInterface</code>, the <code>getItems()</code> function returns an array of <code>GroupInterface</code> data entities.
</p>
When you pass search criteria to a `getList()` call, a search results interface is returned with the search results.

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
`CustomerSearchResultsInterface` returns an array of `CustomerInterface` data entities.
In `GroupSearchResultsInterface`, the `getItems()` function returns an array of `GroupInterface` data entities.

## Service interfaces {#service-interfaces}

<p>Service interfaces include several interface subtypes:</p>
<ul>
<li>Repository interfaces</li>
<li>Management interfaces</li>
<li>Metadata interfaces</li>
</ul>
<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>
<p>Place service interfaces in the top-level <b>Api</b> directory for a module.</p>
Service interfaces include several interface subtypes:

- Repository interfaces
- Management interfaces
- Metadata interfaces

For file names and coding standards, follow the defined [PHP coding standards]({{ page.baseurl }}/coding-standards/code-standard-php.html).

Place service interfaces in the top-level `Api` directory for a module.

### Repository interfaces {#repository-interfaces}

<p>Repository interfaces provide access to persistent data entities.</p>
<p>For example, persistent data entities for the Customer module include Customer, Address, and Group. Consequently, repository interfaces for the Customer module are:</p>
<ul>
<li><code>CustomerRepositoryInterface</code></li>
<li><code>AddressRepositoryInterface</code></li>
<li><code>GroupRepositoryInterface</code></li>
</ul>
<p>Repository interfaces must provide these functions:</p>
Repository interfaces provide access to persistent data entities.

For example, persistent data entities for the Customer module include Customer, Address, and Group. Consequently, repository interfaces for the Customer module are:

- `CustomerRepositoryInterface`
- `AddressRepositoryInterface`
- `GroupRepositoryInterface`

Repository interfaces must provide these functions:

<table style="width:100%">
<tr bgcolor="lightgray">
<th>Function</th>
Expand Down Expand Up @@ -108,11 +114,13 @@ Service contract data interfaces are now mutable.
</td>
</tr>
</table>
<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>

Each data entity has a corresponding interface. Consequently, the `get()` function in the corresponding interface, for example, can return the exact type.

### Management interfaces {#management-interfaces}

<p>Management interfaces provide management functions that are not related to repositories. For example:</p>
Management interfaces provide management functions that are not related to repositories. For example:

<table style="width:100%">
<tr bgcolor="lightgray">
<th>Interface</th>
Expand All @@ -138,8 +146,5 @@ Service contract data interfaces are now mutable.

### Related topics {#related-topics}

<ul>
<li><a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-contracts.html">Service contracts</a></li>
<li><a href="{{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html">Configure services as web APIs</a>
</li>
</ul>
- [Service contracts]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-contracts.html)
- [Configure services as web APIs]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html)
31 changes: 15 additions & 16 deletions guides/v2.2/extension-dev-guide/service-contracts/service-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,30 +16,29 @@ To address these issues, the Magento system introduces _service contracts_.

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

<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).
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.
</p>
<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.
</p>
<p><img src="{{ site.baseurl }}/common/images/msc.jpg"/></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).
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.

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.

![Service Contracts]({{ site.baseurl }}/common/images/msc.jpg)

## Service contract benefits {#msc-benefits}

<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>
<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>.
</p>
<p>Data entities are a side benefit of service contracts.
The database tables that normally support these entities can be complicated.
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).
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).
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.
</p>
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.
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).

Data entities are a side benefit of service contracts.
The database tables that normally support these entities can be complicated.
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).
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).
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.

## Using the @api tag

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

### Related topics {#related-topics}

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