README

Mockingbird External API Client

A Laravel API client for Mockingbird that provides OAuth authentication, strongly typed DTOs powered by Spatie Laravel Data, and convenient service classes for accessing editions, contributors, assets and other Mockingbird resources.

Installation

You can install the package via composer:

composer require wernersoderstrom/mockingbird-api-client

You can publish the config file with:

php artisan vendor:publish --tag="mockingbird-api-client-config"

This is the contents of the published config file:

return [
    'base_url' => env('MOCKINGBIRD_BASE_URL', 'https://tenantname-external-api-app.azurewebsites.net'),
    'oauth_url' => env('MOCKINGBIRD_OAUTH_URL', 'https://tenantname-identity-app.azurewebsites.net/core/connect/token'),
    'client_id' => env('MOCKINGBIRD_CLIENT_ID', 'client_name_here'),
    'client_secret' => env('MOCKINGBIRD_CLIENT_SECRET', 'client_secret_here'),
    'username' => env('MOCKINGBIRD_USERNAME', 'firstname.lastname@tenant.com'),
    'password' => env('MOCKINGBIRD_PASSWORD', 'mockingbird_user_password_here'),
    'scope' => env('MOCKINGBIRD_SCOPE', 'opus'),
];

Usage

The package exposes dedicated services for each API area.

Edition

use Wernersoderstrom\MockingbirdApiClient\Editions\EditionService;

$edition = app(EditionService::class);
$edition = $edition->get('1ca73850-96c2-4ac3-8b98-44d35c9378d1');

Or through dependency injection:

use Wernersoderstrom\MockingbirdApiClient\Editions\EditionService;

final class EditionController
{
    public function __construct(
        private readonly EditionService $edition,
    ) {}

    public function show(string $id)
    {
        return $this->edition->get($id);
    }
}

The service is registered as a singleton and can be resolved from Laravel's service container.

Data objects

Generated by composer docs from the DTO classes, with example values from the public edition in tests/Fixtures/edition.json. Do not edit by hand.

EditionData

Property	Type	Example	Description
`id`	`string`	`1ca73850-96c2-4ac3-8b98-44d35c9378d1`	From `productId`. Mockingbird product ID
`legacyId`	`int`	`244940`	From `editionIdLegacy`
`legacyWorkId`	`int`	`244939`	From `workIdLegacy`
`title`	`string`	`Murtuneet mielet`
`subtitle`	`?string`	`Taistelu suomalaissotilaiden hermoista 1939-1945`
`originalTitle`	`?string`	`null`
`gtin`	`?int`	`9789510374665`	From `ean`. EAN-13 / ISBN-13
`publishingHouse`	`string`	`WSOY`	From `publishingHouse.name`
`brand`	`?string`	`WSOY`	From `brand.name`
`bindingCode`	`BindingCodeData`	BindingCodeData
`isDigital`	`bool`	`false`
`contributors`	`DataCollection<int, ContributorData>`	list of ContributorData
`serie`	`?string`	`null`	From `serie.name`
`costCenter`	`?CostCenterData`	CostCenterData
`season`	`?SeasonData`	SeasonData
`governingCode`	`string`	`Sold out`	From `governingCode.name`
`awards`	`DataCollection<int, AwardData>`	list of AwardData
`keywords`	`array<int, string>`	`["traumat","ENNAKKOTIETO","sotahistoria"]`
`bookTypes`	`array<int, string>`	`[]`
`mainGroup`	`?MainGroupData`	MainGroupData
`subGroup`	`?SubGroupData`	SubGroupData	From `subgroup`
`depth`	`?float`	`37`	From `measurements.depth`. `null` when 0 in Mockingbird
`height`	`?float`	`218`	From `measurements.height`. `null` when 0 in Mockingbird
`weight`	`?float`	`0.615`	From `measurements.weight`. `null` when 0 in Mockingbird
`width`	`?float`	`140`	From `measurements.width`. `null` when 0 in Mockingbird
`languages`	`DataCollection<int, LanguageData>`	list of LanguageData
`originalLanguages`	`DataCollection<int, LanguageData>`	`[]`
`pages`	`?int`	`475`	`null` when 0 in Mockingbird
`prices`	`DataCollection<int, PriceData>`	list of PriceData
`textAndDataMiningProhibited`	`bool`	`false`	From `prohibitTextAndDataMining`
`publishingDate`	`?Carbon`	`2013-08-15T00:00:00+00:00`
`stockBalance`	`?int`	`0`
`technicalProductionTypeName`	`?string`	`BBF Generic`
`vatRate`	`float`	`0.135`	From `vat`. VAT as a fraction, e.g. 0.135 for 13.5 %
`texts`	`DataCollection<int, TextData>`	list of TextData	Marketing texts as HTML, empty texts removed
`dispositionCode`	`string`	`d`	From `dispositionCode.name`
`isMainEdition`	`bool`	`true`	Computed. This edition is the work's main edition
`isWebEdition`	`bool`	`true`	Computed. This edition is the work's web edition
`isTranslated`	`bool`	`false`	Computed. Has a contributor whose role contains "Translator"
`imprint`	`?string`	`null`	Computed. The brand, unless it is Johnny Kniga or the same as the publishing house
`internalTitle`	`?string`	`Murtuneet mielet kirja`	Computed. Title shortened so that it and the format suffix (e.g. `kirja`, `e-kirja`) fit in 50 characters

Method	Description
`printer(): ?ContributorData`	The printer contributor, excluding "Yhteispainatus". `null` for digital products.
`calculatedPublisherRetailPrice(): ?PriceData`	Retail price calculated from the reseller price including VAT. Pocket books, manga and digital products are rounded up to the next 10 cents, everything else to the next .90.
`retailPriceMultiplier(): float`	Multiplier from the reseller price including VAT to the retail price.
`mainEditionCostCenter(): ?CostCenterData`	Cost center of the work.
`mainEditionGtin(): ?int`	GTIN of the work's main edition.

BindingCodeData

Property	Type	Example	Description
`id`	`string`	`BB`
`name`	`string`	`Hardback`
`onixCodelistValue`	`string`	`BB`	ONIX product form code (List 150), mapped from `id`

ContributorData

Property	Type	Example	Description
`contactIdLegacy`	`int`	`55001`
`contactId`	`string`	`00000000-0000-0000-0000-000000000000`
`firstName`	`string`	`Ville`
`lastName`	`?string`	`Kivimäki`
`role`	`ContributorRoleData`	ContributorRoleData
`fullName`	`string`	`Ville Kivimäki`	Computed. First and last name joined with a space

ContributorRoleData

Property	Type	Example	Description
`id`	`int`	`304`	Sent as a numeric string by the API
`name`	`string`	`Author`
`onixCodelistValue`	`?string`	`A01`	ONIX contributor role code (List 17), mapped from `name`. `null` when there is no mapping

CostCenterData

Property	Type	Example	Description
`id`	`int`	`313`	From `code`
`name`	`string`	`WSOY - Tietokirjat`

SeasonData

Property	Type	Example	Description
`year`	`?int`	`2013`	`null` when the period is `N/A`
`period`	`?string`	`Autumn`	`Spring`, `Autumn` or a number. `null` when `N/A`
`name`	`?string`	`2013/2`	Computed. `2026/1` for spring, `2026/2` for autumn, `null` without a year

PriceData

Property	Type	Example	Description
`currency`	`string`	`EUR`	From `price.currency`
`value`	`float`	`41.32`	From `price.value`
`type`	`string`	`PublisherRetailPrice`	From `priceType`
`onixCodelistValue`	`?string`	`41`	ONIX price type code (List 58), mapped from `priceType`. `null` when there is no mapping

LanguageData

Property	Type	Example	Description
`iso639LanguageCode`	`string`	`fin`	From `code`. ISO 639-2/B code, e.g. `fin`
`name`	`string`	`Finnish`

MainGroupData

Property	Type	Example	Description
`id`	`int`	`7`	From `erpId`
`name`	`string`	`Tietokirjallisuus`

SubGroupData

Property	Type	Example	Description
`id`	`int`	`4`	From `erpId`
`name`	`string`	`Historia`

AwardData

Property	Type	Example	Description
`name`	`string`	`Tieto-Finlandia-palkinto`

TextData

Property	Type	Example	Description
`text`	`string`	`Aseiden vaiettua moni veteraani heräsi öisiin painajaisiinsa...`	HTML

StockBalanceData

Property	Type	Example	Description
`gtin`	`int`	`9789510374665`	EAN-13 / ISBN-13 of the edition
`balance`	`int`	`10`	New stock balance

Example

$edition->toArray(), lists shortened to one item

{
    "isMainEdition": true,
    "isWebEdition": true,
    "isTranslated": false,
    "imprint": null,
    "id": "1ca73850-96c2-4ac3-8b98-44d35c9378d1",
    "legacyId": 244940,
    "legacyWorkId": 244939,
    "title": "Murtuneet mielet",
    "subtitle": "Taistelu suomalaissotilaiden hermoista 1939-1945",
    "originalTitle": null,
    "gtin": 9789510374665,
    "publishingHouse": "WSOY",
    "brand": "WSOY",
    "bindingCode": {
        "id": "BB",
        "name": "Hardback",
        "onixCodelistValue": "BB"
    },
    "isDigital": false,
    "contributors": [
        {
            "fullName": "Ville Kivimäki",
            "contactIdLegacy": 55001,
            "contactId": "00000000-0000-0000-0000-000000000000",
            "firstName": "Ville",
            "lastName": "Kivimäki",
            "role": {
                "id": 304,
                "name": "Author",
                "onixCodelistValue": "A01"
            }
        }
    ],
    "serie": null,
    "costCenter": {
        "id": 313,
        "name": "WSOY - Tietokirjat"
    },
    "season": {
        "name": "2013/2",
        "year": 2013,
        "period": "Autumn"
    },
    "governingCode": "Sold out",
    "awards": [
        {
            "name": "Tieto-Finlandia-palkinto"
        }
    ],
    "keywords": [
        "traumat"
    ],
    "bookTypes": [],
    "mainGroup": {
        "id": 7,
        "name": "Tietokirjallisuus"
    },
    "subGroup": {
        "id": 4,
        "name": "Historia"
    },
    "depth": 37,
    "height": 218,
    "weight": 0.615,
    "width": 140,
    "languages": [
        {
            "iso639LanguageCode": "fin",
            "name": "Finnish"
        }
    ],
    "originalLanguages": [],
    "pages": 475,
    "prices": [
        {
            "currency": "EUR",
            "value": 41.32,
            "type": "PublisherRetailPrice",
            "onixCodelistValue": "41"
        }
    ],
    "textAndDataMiningProhibited": false,
    "publishingDate": "2013-08-15T00:00:00+00:00",
    "stockBalance": 0,
    "technicalProductionTypeName": "BBF Generic",
    "vatRate": 0.135,
    "texts": [
        {
            "text": "<p>Aseiden vaiettua moni veteraani heräsi öisiin painajaisiinsa. Mitä he olivat..."
        }
    ],
    "internalTitle": "Murtuneet mielet kirja",
    "dispositionCode": "d"
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

lasselehtinen / mockingbird-api-client

Package info

Security

Fund package maintenance!

Statistics