Postman : Validasi Response API di Postman dengan Ajv dan JSON Schema

Pendahuluan (intro)

Dalam pengujian API, memastikan bahwa response yang dikembalikan oleh endpoint sesuai dengan struktur dan format yang diharapkan merupakan langkah penting. Validasi ini membantu mendeteksi perubahan tak terduga dan mencegah bug sejak dini.

Postman, sebagai salah satu tool populer untuk Testing API, menyediakan fitur untuk melakukan validasi schema response menggunakan pustaka seperti Ajv (Another JSON Schema Validator). Artikel ini membahas cara menerapkan validasi schema pada response API di Postman secara best practices, lengkap dengan logger error yang informatif untuk membantu saat debug.

Bagi teman-teman yang belum tau schema itu apa silahkan baca

Tujuan Validasi Schema

Validasi schema bertujuan untuk memastikan bahwa:

• Struktur data sesuai dengan spesifikasi API (OpenAPI/Swagger).
• Field wajib (required) tersedia dan bertipe data yang benar.
• Tidak ada properti tambahan yang tidak didefinisikan.
• Format data (seperti email, enum, UUID, ISO date) valid.

Studi Kasus (case study)

Dalam kesempatan ini saya ingin menggunakan api login dari repo foodtrip-api local. Pada umumnya untuk api login memilki beberapa data yang wajib disertakan pada response api, yang mana data tersebut akan digunakan untuk menampilkan data sisi FE (FrontEnd). Dari sini kita dapat melihat kemungkinan masalah yang akan muncul.

Problem

1. Bagaimana memastikan response api mempunyai format data yang konsisten?
2. Bagaimana mendeteksi jika ada perubahan field data yang tidak diketahui QA?
3. Bagaimana cara mudah melakukan pengecekan field enum?

Sebelum kita menyelaikan 3 masalah diatas mari kita mulai dengan membuat request di postman.

Setelah itu kita lanjut untuk membuat script untuk validasi respone api tersebut. untuk basic data yang akan kita validasi.

• – validate response memiliki data yang benar?
• – validate token yang valid?
• – validate semua field yang dibutuhkan fe?

contoh script nya seperti berikut :

const {data, token, message} = pm.response.json()

pm.test('Verify response Data must me valid data', ()=>{
    pm.expect(data.email_address).to.eq(pm.environment.get('emailCustomer'))
    pm.expect(data.user_type).to.eq('Customer')
    pm.expect(token).not.to.eq(null)
})

pm.test('Verify response message', ()=>{
    pm.expect(message).to.eq('User has been successfully login')
})

Hasil dari script yang kita buat sebelumnya seperti diatas. Mungkin teman-teman memperhatikan bahwa script yang kita buat masih belum menghandel validasi untuk setiap field yang dibutuhkan fe. Kita bisa menggunakan fn Object.entries() untuk pengecekan setiap field yang ada namun itu kurang direcomandasikan karena cukup ribet dan susah di maintenance jika ada perubahan. Oleh karena itu kita akan memanfaatkan schema validation untuk membantu kita menyelesaikan masalah tersebut.

Mari kita coba implementasikan schema validation. Untuk schema sendiri biasanya akan di berikan oleh team dev, namun jika teman-teman tidak memiliki bisa generated online, salah satu website generator schema faporit saya https://jsonschema.net

var Ajv = require('ajv');
const ajv = new Ajv({ logger: console, allErrors: true });

pm.test('Schema is valid', function () {
  const schema = {
    type: 'object',
    properties: {
      error: { type: 'boolean' },
      data: {
        type: 'object',
        properties: {
          user_id: { type: 'string' },
          resto_id: { type: ['string', 'null'] },
          user_no: { type: 'string' },
          first_name: { type: 'string' },
          middle_name: { type: ['string', 'null'] },
          last_name: { type: 'string' },
          email_address: { type: 'string' },
          phone_number: { type: ['string', 'null'] },
          gender: {
            type: ['string', 'null'],
            enum: ['Male', 'Female', 'Others'],
          },
          user_type: {
            type: 'string',
            enum: ['Customer', 'Resto_Admin', 'Admin'],
          },
          created_by: { type: ['string', 'null'] },
          updated_by: { type: ['string', 'null'] },
          deleted_by: { type: ['string', 'null'] },
          date_created: { type: 'string' },
          date_updated: { type: 'string' },
          date_deleted: { type: ['string', 'null'] },
        },
        required: [
          'user_id',
          'user_no',
          'first_name',
          'last_name',
          'email_address',
          'user_type',
          'created_by',
          'date_created',
          'date_updated',
        ],
      },
      token: { type: 'string' },
      message: { type: 'string' },
    },
    required: ['error', 'data', 'token', 'message'],
  };
  pm.expect(
    ajv.validate(schema, pm.response.json()),
    JSON.stringify(ajv.errors)
  ).to.be.true;
});

Dengan tambahan script di atas kita sudah menyelesaikan semua response yang perlu di validasi. sekarang bagaimana jika ingin implementasi schema validation ke api lainnya. Mungkin jika hanya api beberapa api yang perlu di test, copy paste code diatas menjadi solusi namun jika banyak api maka akan sulid di maintenance.

Membuat Funtion Helper untuk schema validation di postman

untuk membuat helper funtion di postman ada beberapa cara, salah satu yang biasa saya gunakan adalah menyimpan fn di env dan dipanggil seperti biasa seperti variable pada umumnya, tinggal kita tambahkan eval. agar script nya bisa digunakan di semua collection, kita bisa meletakan code kita di parent folder (Pre-request Script). contoh nya seperti dibawah ini.

if (!pm.environment.get('validateSchemaHelper')) {
    function validateSchema(data, schema) {
        const Ajv = require('ajv');
        const ajv = new Ajv({ allErrors: true, strict: false });
        const validate = ajv.compile(schema);
        const isValid = validate(data);

        if (!isValid) {
            console.log("Schema validation errors:");
            validate.errors.forEach((err) => {
                console.log(err)
                console.log(`[${err.dataPath || '/'}] ${err.message}`);
            });

            const messages = validate.errors.map(
                (e) => `[${e.dataPath || '/'}] ${e.message}`
            );
            throw new Error("Schema Validation Failed:\n" + messages.join("\n"));
        }

        return true;
    }

    pm.environment.set("validateSchemaHelper", validateSchema.toString());
}

untuk cara menggunakannya seperti dibawah ini

cara menggunakan validateSchemaHelper

const validateSchema = pm.environment.get('validateSchemaHelper');
const { data, token, message } = pm.response.json();
const schema = {
  type: 'object',
  properties: {
    error: { type: 'boolean' },
    data: {
      type: 'object',
      properties: {
        user_id: { type: 'string' },
        resto_id: { type: ['string', 'null'] },
        user_no: { type: 'string' },
        first_name: { type: 'string' },
        middle_name: { type: ['string', 'null'] },
        last_name: { type: 'string' },
        email_address: { type: 'string' },
        phone_number: { type: ['string', 'null'] },
        gender: {
          type: ['string', 'null'],
          enum: ['Male', 'Female', 'Others'],
        },
        user_type: {
          type: 'string',
          enum: ['Customer1', 'Resto_Admin', 'Admin'],
        },
        created_by: { type: ['string', 'null'] },
        updated_by: { type: ['string', 'null'] },
        deleted_by: { type: ['string', 'null'] },
        date_created: { type: 'string' },
        date_updated: { type: 'string' },
        date_deleted: { type: ['string', 'null'] },
      },
      required: [
        'user_id',
        'user_no',
        'first_name',
        'last_name',
        'email_address',
        'user_type',
        'created_by',
        'date_created',
        'date_updated',
      ],
    },
    token: { type: 'string' },
    message: { type: 'string' },
  },
  required: ['error', 'data', 'token', 'message'],
};

pm.test('Schema is valid', function () {
  eval(validateSchema);
  validateSchema(pm.response.json(), schema);
});

Manfaat menggunakan code diatas kita akan lebih mudah untuk melakukan pengecekan struktur response pada setiap response api yang kita test dan mempermudah kita maintenance code kita. Dengan kode yang kita buat maka masalah yang kita bahas sebekumnya dapat terselesaikan.

note. Jika melakukan perubahan pada fn validateSchemaHelper, anda harus menghapus value saat ini terlebih dahulu. karena saya membuat hanya insert ketika value validateSchemaHelper null.

Summary

Dalam pengujian API, memastikan struktur dan isi dari response API sangat krusial agar integrasi antar sistem berjalan mulus dan bug dapat dideteksi lebih awal. Kita telah membahas pentingnya schema validation dalam Postman menggunakan pustaka Ajv serta bagaimana menerapkannya secara efisien dan reusable.

Melalui studi kasus login API, kita melihat bagaimana validasi manual cepat menjadi tidak efektif ketika field bertambah atau berubah. Dengan menggunakan JSON Schema dan helper function validateSchema, kita dapat memastikan setiap field wajib tersedia, format data sesuai (email, UUID, enum), dan tidak ada properti tak terdefinisi.

Lebih lanjut, kita juga telah mencoba membuat fungsi helper reusable yang disimpan di Environment, sehingga dapat digunakan di berbagai request tanpa deklarasi ulang. Hal ini tidak hanya mempermudah maintenance, tetapi juga membantu QA untuk cepat menemukan perubahan yang tak terduga dari sisi response.

Dengan pendekatan ini, masalah seperti:

• field hilang atau berubah tanpa diketahui,
• enum tidak valid,
• struktur response yang tidak sesuai dokumentasi,

bisa diselesaikan dengan cepat dan konsisten.

semoga bermanfaat