Sync API

Sync API is the synchronous API that Spryker supports. In the Spryker terminology, it is also known as Glue API with its REST API B2C Demo Shop and REST API B2B Demo Shop endpoints. The schema files we use follow the OpenAPI specification. Spryker uses schema files to generate code for your project, including predefined test cases. The purpose of doing so is to let you focus on building your business logic without caring about the boilerplate code.

Code generation

You can use the Sync API’s OpenAPI schema file to generate code with the help of Spryks. You can control the code generator with the following parts of the schema file:

• Paths
• Extension
• Application type
• Components

Paths

When you design your resource names, keep in mind that the code generator, by default, uses the path to define the following:

• module the endpoint belongs to,
• controller name that will handle the request,
• model name that will be used to fulfill your business logic.

For example, /customers/addresses generates code within the CustomersBackendApi or CustomersFrontendApi module (see Application type). The controller name that will be executed to handle the request will be AddressesController and the model name will be Addresses.

Extension

Inside your path definition, you can manipulate the generated code. For example:

paths:
    /customers/addresses:
        post:
            x-spryker:
                module: Users # Changes the module name
                controller: UserAddresses # Changes the controller and the model name

This tells the code generator to add the code to the UsersBackendApi module. The controller name will be UserAddressesController and the model name will be UserAddresses.

The x-spryker extension gives you control over the generated code.

Application type

Spryker offers two types of API Applications: a frontend API and a backend API. The application type you build depends on your specific needs. The default one is backend. You can define the application type with the console command that builds the code from a given schema file.

Components

Within the Components section, you describe the data contract for your API endpoints. You always need to define three schemas for one endpoint. Here is an example of a response your API returns:

paths:
    /customers/addresses:
        post:
            ...
            responses:
                200:
                    description: 'Expected response to a valid request.'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FooBarApiResponse'
components:
    schemas:
        FooBarApiResponse:
            properties:
                data:
                    $ref: '#/components/schemas/FooBarApiResponseData'
        FooBarApiResponseData:
            properties:
                type:
                    type: 'string'
                attributes:
                    $ref: '#/components/schemas/FooBarApiResponseAttributes'
        FooBarApiResponseAttributes:
            properties:
                name:
                    type: string

This returns the following JSON structure:

{
  "data": {
    "type": "string",
    "attributes": {
      "name": "string"
    }
  }
}

For all three components, the code generator creates a transfer schema file definition within the module that was defined in the path section.

Troubleshooting

when

There is the following error: Failed to resolve Reference '#/paths/my/app/path/.... Example output:

php vendor/bin/syncapi code:openapi:generate -f config/app/bazaarvoice/api/openapi/bazaarvoice.yml

In Reference.php line 255:

  Failed to resolve Reference '#/paths/bazaar-voice/configure/post' to cebe\openapi\spec\Operation Object: Failed to evaluate pointer '/paths/bazaar-voice/configure/post'. Array has no member bazaar-voice at path '/paths'.  


In JsonPointer.php line 123:

  Failed to evaluate pointer '/paths/bazaar-voice/configure/post'. Array has no member bazaar-voice at path '/paths'.  


code:openapi:generate [-f|--openapi-file OPENAPI-FILE] [-t|--application-type APPLICATION-TYPE] [-o|--organization ORGANIZATION]

then

This is typically caused by forward slashes (/) or tilde (~) characters that are not properly escaped in the referenced path. If you wish to refer to the path /blogs/{blog_id}/new~posts, your reference must look like this:

$ref: '#/paths/~1blogs~1{blog_id}~1new~0posts'

See Using $ref in the Swagger documentation for more information about escaping these characters.