Anotasi dan sintaksis Cloud Endpoints Frameworks

Anotasi Framework Endpoint menjelaskan konfigurasi API, metode, parameter, dan detail penting lainnya yang menentukan properti dan perilaku endpoint.

Lihat Menulis dan membuat anotasi kode untuk mengetahui informasi tentang cara menambahkan anotasi menggunakan project Maven. Artefak Cloud Endpoints App Engine Maven disediakan untuk membuat dan mem-build API backend, serta membuat library klien dari API tersebut.

Anotasi yang menentukan konfigurasi dan perilaku di seluruh API (memengaruhi semua class yang diekspos dalam API dan semua metodenya) adalah @Api. Semua metode publik, non-statis, dan non-bridge dari class yang dianotasikan dengan @Api akan ditampilkan dalam API publik.

Jika memerlukan konfigurasi API khusus untuk metode tertentu, Anda dapat memilih untuk menggunakan @ApiMethod untuk menetapkan konfigurasi per metode. Anda mengonfigurasi anotasi ini dengan menyetel berbagai atribut, seperti yang ditunjukkan dalam tabel berikut.

@Api: Anotasi cakupan API

Anotasi @Api mengonfigurasi seluruh API, dan berlaku untuk semua metode publik dari suatu class kecuali jika diganti oleh @ApiMethod.

Untuk mengganti anotasi @Api tertentu untuk class tertentu dalam API, lihat @ApiClass dan @ApiReference.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.Api;

Atribut

Atribut @Api Deskripsi Contoh
audiences Diperlukan jika API Anda memerlukan autentikasi dan jika Anda mendukung klien Android. Untuk informasi selengkapnya, lihat Client ID dan audiens. audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"}
apiKeyRequired Opsional. Digunakan untuk membatasi akses ke permintaan yang menyediakan kunci API. apiKeyRequired = AnnotationBoolean.TRUE
authenticators Diperlukan jika API Anda melakukan autentikasi menggunakan Firebase, Auth0, atau akun layanan. Atribut ini tidak diperlukan jika API Anda melakukan autentikasi menggunakan token ID Google. Anda dapat menetapkannya pada level API atau pada level metode individual. Setel ke {EspAuthenticator.class}, atau Anda dapat menulis pengautentikasi kustom Anda sendiri, seperti yang dijelaskan dalam Pengautentikasi Antarmuka. authenticators = {EspAuthenticator.class}
backendRoot Tidak digunakan lagi. Untuk menyalurkan API dari jalur yang berbeda, pada file web.xml, ubah url-pattern di bagian EndpointsServlet. <url-pattern>/example-api/*</url-pattern>
canonicalName Digunakan untuk menentukan nama yang berbeda atau lebih mudah dibaca untuk API di library klien. Nama ini digunakan untuk membuat nama di library klien; API backend terus menggunakan nilai yang ditentukan di properti name.

Misalnya, jika API Anda menetapkan name ke dfaanalytics, Anda dapat menggunakan properti ini untuk menentukan nama kanonis DFA Group Analytics; class klien yang dihasilkan selanjutnya akan berisi nama DfaGroupAnalytics.

Anda harus menyertakan spasi yang relevan di antara nama-nama tersebut, dan diganti dengan camel kapitalisasi yang sesuai.		 canonicalName = "DFA Analytics:"n
clientIds Diperlukan jika API Anda menggunakan autentikasi. Daftar client ID untuk klien yang diizinkan meminta token. Untuk informasi selengkapnya, lihat Client ID dan audiens. clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"}
defaultVersion Menentukan apakah versi default digunakan jika tidak ada yang disediakan dalam atribut version. defaultVersion = AnnotationBoolean.TRUE
description Deskripsi singkat tentang API. Bagian ini diekspos dalam layanan discovery untuk mendeskripsikan API Anda, dan dapat juga digunakan untuk membuat dokumentasi. description = "Sample API for a simple game"
documentationLink URL tempat pengguna dapat menemukan dokumentasi tentang versi API ini. Hal ini akan muncul di sorotan "Pelajari Lebih Lanjut" API Explorer di bagian atas halaman API Explorer agar pengguna dapat mempelajari layanan Anda. documentationLink = "http://link_to/docs"
issuers Konfigurasi penerbit JWT kustom. issuers = { @ApiIssuer(name = "auth0", issuer = "https://test.auth0.com/authorize", jwksUri = "https://test.auth0.com/.well-known/jwks.json") }
issuerAudiences Audiens untuk masing-masing penerbit. issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) }
limitDefinitions Opsional. Digunakan untuk menentukan quotas API Anda. Lihat @ApiLimitMetric. limitDefinitions = { @ApiLimitMetric(name = "read-requests", displayName = "Read requests", limit = 1000)}
name Nama API, yang digunakan sebagai awalan untuk semua metode dan jalur API. Nilai name:
  • Harus dimulai dengan huruf kecil
  • Harus cocok dengan ekspresi reguler [a-z]+[A-Za-z0-9]*
Jika Anda tidak menentukan name, myapi default akan digunakan.		 name = "foosBall"
namespace Mengonfigurasi ruang nama untuk klien yang dihasilkan. Lihat @ApiNamespace. namespace=@ApiNamespace(ownerDomain="your-company.com", ownerName="YourCo", packagePath="cloud/platform")
root Tidak digunakan lagi. Untuk menyalurkan API dari jalur yang berbeda, pada file web.xml, ubah url-pattern di bagian EndpointsServlet. <url-pattern>/example-api/*</url-pattern>
scopes Jika tidak diberikan, defaultnya adalah cakupan email (https://www.googleapis.com/auth/userinfo.email), yang diperlukan untuk OAuth. Anda dapat menggantinya untuk menentukan lebih banyak cakupan OAuth 2.0, jika diinginkan. Namun, jika Anda menentukan lebih dari satu cakupan, perhatikan bahwa pemeriksaan cakupan akan lulus jika token dibuat untuk salah satu cakupan yang ditentukan. Untuk mewajibkan beberapa cakupan, String tunggal harus ditentukan dengan spasi di antara setiap cakupan. Untuk mengganti cakupan yang ditetapkan di sini untuk metode API tertentu, tentukan cakupan yang berbeda dalam anotasi @ApiMethod. scopes = {"ss0", "ss1 and_ss2"}
title Teks yang ditampilkan di API Explorer sebagai judul API Anda, serta diekspos dalam penemuan dan layanan direktori. title = "My Backend API"
transformers Menentukan daftar Transformer kustom. Perhatikan bahwa ada anotasi alternatif (@ApiTransformer) yang lebih disarankan. Atribut ini diganti oleh @ApiTransformer. transformers = {BazTransformer.class}
version Menentukan versi endpoint. Jika Anda tidak memberikannya, v1 default akan digunakan. version = "v2"

Contoh anotasi @Api

Anotasi ini ditempatkan sebelum definisi class:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

Client-ID dan audiens

Untuk autentikasi OAuth2, token OAuth2 diterbitkan ke client ID tertentu, yang berarti Anda dapat menggunakan client ID untuk membatasi akses ke API. Saat mendaftarkan aplikasi Android di Konsol Google Cloud, Anda membuat client ID untuk aplikasi tersebut. Client ID ini adalah ID yang meminta token OAuth2 dari Google untuk tujuan autentikasi. Jika API backend dilindungi oleh autentikasi, token akses OAuth2 akan dikirim dan dibuka oleh Endpoint, client ID diekstrak dari token, lalu ID tersebut dibandingkan dengan daftar client ID yang dapat diterima yang dideklarasikan backend (daftar clientIds).

Jika ingin Endpoints API mengautentikasi pemanggil, Anda harus menyediakan daftar clientIds yang diizinkan untuk meminta token. Daftar ini harus berisi semua client ID yang Anda peroleh melalui Google Cloud Console untuk klien web atau Android Anda. Artinya, klien harus diketahui pada waktu build API. Jika Anda menetapkan daftar kosong, {}, tidak ada klien yang dapat mengakses metode yang dilindungi oleh Auth.

Jika Anda menggunakan atribut clientIds dan ingin menguji panggilan yang diautentikasi ke API menggunakan Google API Explorer, Anda harus menyediakan client ID-nya dalam daftar clientIds: nilai yang akan digunakan adalah com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID.

Tentang audiens

Daftar clientIds melindungi API backend dari klien yang tidak sah. Namun, perlindungan lebih lanjut diperlukan untuk melindungi klien, sehingga token autentikasinya hanya berfungsi untuk API backend yang dimaksud. Untuk klien Android, mekanisme ini adalah atribut audiences, tempat Anda menetapkan client ID API backend.

Perlu diperhatikan bahwa saat Anda membuat project konsol Google Cloud, client ID default akan otomatis dibuat dan diberi nama untuk digunakan oleh project tersebut. Saat Anda mengupload backend API ke App Engine, API tersebut akan menggunakan client ID tersebut. Ini adalah client ID web yang disebutkan dalam autentikasi API.

@ApiMethod: Anotasi cakupan metode

Anotasi @ApiMethod digunakan untuk menyediakan konfigurasi API yang berbeda dengan default yang disediakan oleh anotasi @Api atau @ApiClass. Perhatikan bahwa ini bersifat opsional: semua metode publik, non-statis, dan non-bridge di class dengan anotasi @Api akan ditampilkan di API, baik metode tersebut memiliki anotasi @ApiMethod atau tidak.

Atribut dalam anotasi ini memungkinkan Anda mengonfigurasi detail satu metode API. Jika atribut yang sama ditentukan dalam @Api dan @ApiMethod, @ApiMethod akan diganti.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.AnnotationBoolean;
import com.google.api.server.spi.config.ApiMethod;
import com.google.api.server.spi.config.ApiMethod.HttpMethod;

Atribut

Atribut @ApiMethod Deskripsi Contoh
apiKeyRequired Opsional. Digunakan untuk membatasi akses ke permintaan yang menyediakan Kunci API. apiKeyRequired = AnnotationBoolean.TRUE
audiences Berikan ini jika Anda ingin mengganti konfigurasi di @API. Untuk informasi selengkapnya, lihat Client ID dan audiens. audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"}
authenticators Diperlukan jika API Anda melakukan autentikasi menggunakan Firebase, Auth0, atau akun layanan, dan Anda belum menetapkan atribut ini di level API. Atribut ini tidak diperlukan jika API Anda melakukan autentikasi menggunakan token ID Google. Setel ke {EspAuthenticator.class}, atau Anda dapat menulis pengautentikasi kustom Anda sendiri, seperti yang dijelaskan dalam Pengautentikasi Antarmuka authenticators = {EspAuthenticator.class}
clientIds Daftar client ID untuk klien yang diizinkan meminta token. Diperlukan jika API Anda menggunakan autentikasi. clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"}
httpMethod Metode HTTP yang akan digunakan. Jika Anda tidak menetapkannya, nilai default akan dipilih berdasarkan nama metode. httpMethod = HttpMethod.GET
issuerAudiences Berikan ini jika Anda ingin mengganti konfigurasi di @Api. issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) }
metricCosts Opsional. Menunjukkan bahwa metode memiliki batas kuota. Anda menetapkan anotasi @ApiMetricCost ke metricCosts. Anda juga harus menentukan atribut limitDefinitions untuk menentukan kuota dalam anotasi @Api. Anotasi @ApiMetricCost menggunakan atribut berikut:
  • name: Nama yang Anda tentukan dalam anotasi ApiLimitMetric.
  • biaya: Bilangan bulat yang menentukan biaya untuk setiap permintaan. Biaya ini memungkinkan metode untuk menggunakan dengan tarif yang berbeda dari kuota yang sama. Misalnya, jika kuota memiliki batas 1.000 dan biaya 1, aplikasi panggilan dapat membuat 1.000 permintaan per menit sebelum melampaui batas. Dengan biaya 2 untuk kuota yang sama, aplikasi panggilan hanya dapat membuat 500 permintaan per menit sebelum melampaui batas.
 metricCosts = { @ApiMetricCost(name = read-requests", cost = 1) }
name Nama untuk metode ini dalam library klien yang dihasilkan. Nama ini otomatis diawali dengan nama API Anda guna membuat nama unik untuk metode tersebut. Nilai name:
  • Harus dimulai dengan huruf kecil
  • Harus cocok dengan ekspresi reguler [a-z]+[A-Za-z0-9]*
Jika Anda tidak menentukan name, myapi default akan digunakan.		 name = "foosBall.list"
path Jalur URI yang akan digunakan untuk mengakses metode ini. Jika Anda tidak menetapkannya, jalur default akan digunakan berdasarkan nama metode Java. Jika Anda berencana untuk menambahkan pengelolaan API, jangan sertakan garis miring di jalur direktori. path = "foos"
scopes Tentukan satu atau beberapa cakupan OAuth 2.0 yang salah satunya diperlukan untuk memanggil metode ini. Jika Anda menetapkan scopes untuk suatu metode, setelan tersebut akan diganti dalam anotasi @Api. Jika Anda menentukan lebih dari satu cakupan, perhatikan bahwa pemeriksaan cakupan akan lulus jika token dibuat untuk salah satu cakupan yang ditentukan. Untuk mewajibkan beberapa cakupan, tentukan satu String dengan spasi di antara setiap cakupan. scopes = {"ss0", "ss1 and_ss2"}

Contoh anotasi @ApiMethod

Anotasi ini ditempatkan sebelum definisi metode di dalam class:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(
    name = "sayHiUser",
    httpMethod = ApiMethod.HttpMethod.GET)
public MyBean sayHiUser(@Named("name") String name, User user)
    throws OAuthRequestException, IOException {
  MyBean response = new MyBean();
  response.setData("Hi, " + name + "(" + user.getEmail() + ")");

  return response;
}

Metode yang menggunakan entity sebagai parameter harus menggunakan HttpMethod.POST (untuk operasi penyisipan) atau HttpMethod.PUT (untuk operasi update):

@ApiMethod(
    name = "mybean.insert",
    path = "mybean",
    httpMethod = ApiMethod.HttpMethod.POST
)
public void insertFoo(MyBean foo) {
}

@Named

Anotasi @Named diperlukan untuk semua parameter jenis non-entity yang diteruskan ke metode sisi server. Anotasi ini menunjukkan nama parameter dalam permintaan yang dimasukkan di sini. Parameter yang tidak dianotasi dengan @Named dimasukkan dengan seluruh objek permintaan.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import javax.inject.Named;

Contoh ini menunjukkan penggunaan @Named:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(name = "sayHi")
public MyBean sayHi(@Named("name") String name) {
  MyBean response = new MyBean();
  response.setData("Hi, " + name);

  return response;
}

dengan @Named menentukan bahwa hanya parameter id yang dimasukkan dalam permintaan.

@ApiLimitMetric

Bagian ini menjelaskan anotasi yang diperlukan untuk menentukan quotas untuk API Anda. Baca artikel Mengonfigurasi kuota untuk mengetahui semua langkah yang diperlukan dalam menyiapkan kuota.

Anda menetapkan anotasi @ApiLimitMetric ke atribut limitDefinitions dari anotasi cakupan API. Anda juga harus menambahkan @ApiMetricCost ke anotasi @ApiMethod untuk setiap metode yang ingin Anda terapkan kuotanya.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiLimitMetric;

Atribut

Atribut @ApiLimitMetric

Deskripsi
name Nama kuota. Biasanya, ini adalah jenis permintaan (misalnya, "read-requests" atau "write-requests") yang mengidentifikasi kuota secara unik
displayName Teks yang ditampilkan untuk mengidentifikasi kuota pada tab Quotas di halaman Endpoint > Services di Konsol Google Cloud. Teks ini juga ditampilkan kepada konsumen API Anda di halaman Quotas di IAM & admin dan API & services. Nama tampilan harus berisi maksimum 40 karakter.
Agar mudah dibaca, teks "per menit per project" akan otomatis ditambahkan ke nama tampilan di halaman Quotas.
Agar konsisten dengan nama tampilan layanan Google yang tercantum di halaman Quotas yang dilihat konsumen API Anda, sebaiknya gunakan hal berikut untuk nama tampilan:
  • Gunakan "Permintaan" jika Anda hanya memiliki satu metrik.
  • Jika Anda memiliki beberapa metrik, masing-masing metrik harus menjelaskan jenis permintaan dan berisi kata "permintaan" (misalnya "Permintaan baca" atau "Permintaan tulis").
  • Gunakan "unit kuota", bukan "permintaan" jika biaya untuk kuota ini lebih besar dari 1.
batas Nilai bilangan bulat yang merupakan jumlah maksimum permintaan per menit per project konsumen untuk kuota.

Contoh

limitDefinitions = {
      @ApiLimitMetric(
        name = "read-requests",
        displayName = "Read requests",
        limit = 1000),
      @ApiLimitMetric(
        name = "write-requests",
        displayName = "Write requests",
        limit = 50),
    }

@ApiNamespace

Anotasi @ApiNamespace menyebabkan library klien yang dihasilkan memiliki namespace yang Anda tentukan, bukan default yang dibuat selama pembuatan library klien.

Secara default, jika Anda tidak menggunakan anotasi ini, namespace yang digunakan adalah kebalikan dari your-project-id.appspot.com. Artinya, jalur paketnya adalah com.appspot.your-project-id.yourApi.

Anda dapat mengubah namespace default dengan menyediakan anotasi @ApiNamespace dalam anotasi @Api:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

Tetapkan atribut ownerDomain ke domain perusahaan Anda sendiri dan ownerName ke nama perusahaan Anda, misalnya, your-company.com. Kebalikan dari ownerDomain digunakan untuk jalur paket: com.your-company.yourApi.

Anda dapat memilih menggunakan atribut packagePath untuk memberikan cakupan lebih lanjut. Misalnya, dengan menetapkan packagePath ke cloud, jalur paket yang digunakan di library klien adalah com.your-company.cloud.yourApi. Anda dapat menambahkan lebih banyak nilai ke jalur paket dengan memberikan pemisah /: packagePath="cloud/platform".

@Nullable

Anotasi ini menunjukkan bahwa parameter metode bersifat opsional (dan oleh karena itu, parameter kueri). @Nullable hanya dapat digunakan dengan parameter @Named.

@ApiClass

Dalam multiclass API, Anda dapat menggunakan @ApiClass untuk menentukan properti yang berbeda untuk class tertentu, yang akan menggantikan properti setara dalam konfigurasi @Api. Lihat Menggunakan @ApiClass untuk properti yang dapat berbeda di antara class untuk mengetahui deskripsi lengkap anotasi ini.

@ApiReference

Dalam multiclass API, Anda dapat menggunakan @ApiReference untuk menyediakan metode alternatif pewarisan anotasi. Lihat Menggunakan pewarisan @ApiReference untuk deskripsi lengkap anotasi ini.

@ApiResourceProperty

@ApiResourceProperty memberikan kontrol atas cara properti resource ditampilkan di API. Anda dapat menggunakannya pada pengambil atau penyetel properti untuk menghapus properti dari resource API. Anda juga dapat menggunakannya di kolom itu sendiri, jika kolom bersifat pribadi, untuk mengeksposnya dalam API. Anda juga dapat menggunakan anotasi ini untuk mengubah nama properti di resource API.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiResourceProperty;
import com.google.api.server.spi.config.AnnotationBoolean;

Atribut

Atribut @ApiResourceProperty Deskripsi Contoh
ignored Jika ditetapkan ke AnnotationBoolean.TRUE, properti akan dihilangkan. Jika tidak ditentukan atau ditetapkan ke AnnotationBoolean.FALSE, properti tidak dihilangkan. @ApiResourceProperty(ignored = AnnotationBoolean.TRUE)
name Jika diberikan, atribut ini akan menentukan nama properti yang akan diekspos di API. @ApiResourceProperty(name = "baz")

Class contoh dengan @ApiResourceProperty

Cuplikan berikut menunjukkan class dengan pengambil properti yang dianotasi dengan @ApiResourceProperty:


class Resp {
  private String foobar = "foobar";
  private String bin = "bin";

  @ApiResourceProperty
  private String visible = "nothidden";

  @ApiResourceProperty(ignored = AnnotationBoolean.TRUE)
  public String getBin() {
    return bin;
  }

  public void setBin(String bin) {
    this.bin = bin;
  }

  @ApiResourceProperty(name = "baz")
  public String getFoobar() {
    return foobar;
  }

  public void setFoobar(String foobar) {
    this.foobar = foobar;
  }
}

public Resp getResp() {
  return new Resp();
}

Dalam cuplikan kode sebelumnya, @ApiResourceProperty diterapkan ke pengambil getBin untuk properti bin, dengan setelan atribut ignored yang memberi tahu Endpoints Frameworks untuk menghapus properti ini di resource API.

@ApiResourceProperty juga diterapkan ke kolom pribadi visible, yang tidak memiliki pengambil atau penyetel. Penggunaan anotasi ini akan mengekspos kolom ini sebagai properti dalam resource API.

Dalam cuplikan yang sama, @ApiResourceProperty juga diterapkan ke pengambil yang berbeda, getFoobar, yang menampilkan nilai properti untuk properti foobar. Atribut name dalam anotasi ini memberi tahu Framework Endpoint untuk mengubah nama properti di resource API. Nilai properti itu sendiri tidak berubah.

Dalam contoh cuplikan sebelumnya, representasi JSON dari objek Resp terlihat mirip dengan yang berikut ini:

{"baz": "foobar", "visible": "nothidden"}

@ApiTransformer

Anotasi @ApiTransformer menyesuaikan cara suatu jenis diekspos di Endpoint melalui transformasi ke dan dari jenis lain. (Transformer yang ditentukan harus merupakan implementasi dari com.google.api.server.spi.config.Transformer.)

Menggunakan anotasi @ApiTransformer pada class adalah cara yang lebih disukai untuk menentukan Transformer. Namun, Anda dapat menentukan transformer kustom dalam atribut transformer anotasi @Api.

Impor yang diperlukan

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiTransformer;

Class contoh dengan @ApiTransformer

Cuplikan berikut menunjukkan class yang dianotasi dengan @ApiTransformer:


@ApiTransformer(BarTransformer.class)
public class Bar {
  private final int x;
  private final int y;

  public Bar(int x, int y) {
    this.x = x;
    this.y = y;
  }

  public int getX() {
    return x;
  }

  public int getY() {
    return y;
  }
}

Class ini ditransformasikan oleh class BarTransformer.

Contoh class transformer Endpoints

Cuplikan berikut menunjukkan contoh class transformer yang bernama BarTransformer. Ini adalah transformer yang dirujuk oleh @ApiTransformer dalam cuplikan sebelumnya:

public class BarTransformer implements Transformer<Bar, String> {
  public String transformTo(Bar in) {
    return in.getX() + "," + in.getY();
  }

  public Bar transformFrom(String in) {
    String[] xy = in.split(",");
    return new Bar(Integer.parseInt(xy[0]), Integer.parseInt(xy[1]));
  }
}

Dengan asumsi ada objek dengan properti bar dari jenis Bar, tanpa transformator sebelumnya, objek tersebut direpresentasikan sebagai:

{"bar": {"x": 1, "y": 2}}

Dengan transformer, objek akan direpresentasikan sebagai:

{"bar": "1,2"}