Cómo crear service contracts para la interacción con la bbdd

La estructura básica de un repository es la siguiente:

    ├───Api
    │   │   nombreTablaRepositoryInterface.php
    │   │
    │   └───Data
    │           nombreTablaInterface.php
    │
    └───Model
        │   nombreTabla.php
        │   nombreTablaRepository.php
        │
        └───ResourceModel
            │   nombreTabla.php
            │
            └───nombreTabla
                    collection.php

En Api, creamos las interfaces. En Api/Data, creamos, las interfaces de setters y getters de los campos de la tabla. Es importante destacar su importancia. Por ej: cuando creamos un formulario con campos con el mismo name que que el nombre de las propiedades definidas en los fichros de api/data, entonces podemos pasarles le valor $data ->addData($data), y Magento automáticamente se hará el match de los nombres.
En Api, creamos las interfaces para otras finalidades, por ej: repositorios.

En Model, creamos nombreTabla.php implementando la interfaz del Api/data. En ResourceModel creamos el nombreTabla.php, este fichero le llamaremos comúnemente como recurso, es decir que se conectará a la bbdd a través de este fichero. Es por eso que ponemos el nombre de la tabla y el primary key en en el método init(). En la carpeta nombreTabla, estará el fichero collection.php, que conecta el modelo con el resource. Asociando las propiedades del modelo con los campos. Hay que marcar que un modelo que tiene primary key id, magento no lo considerará como un objeto nuevo y no hará el insert de esos valores sino hará un update.

Vamos a hablar ahora de los repositories, no son más que métodos que facilitan las tareas de crud. Sin los repositories también podremos hacer crud, usando directamente resourceModel , collection etc. Los repositories sólo facilitan las tareas y reutilización de métodos. Podría llamarse con cualquier nombre, pero según la convención , le llaman repository.
El repository implementa las interfaces que están en Api. Y básicamente serán métodos: save, delete, getList etc

En el repository cuando queremos traer un conjunto de datos, usaremos el getList, normalmente tendrá un parametro del tipo SearchCriteria. Pero no necesaria sea así.