Users Search V2 Entegrasyon Dokumani

Migration rehberi

Yapılandırma sırası için Migration şablonu. Yeni düzenlemelerde Amaç → Önkoşullar → Endpoint → Request/Response → Hata kodları → Client adımları → İlgili sayfalar bölümlerini tercih edin.

Temel Bilgiler

Ad: Users Search V2
Endpoint: GET /api/v2/users/search
Auth: Bearer Token (JWT) zorunlu
Controller: users
Versiyonlama: URI versioning (/api/v2/...)

Bu doküman users search v2 endpointinin entegrasyon sozlesmesini (query DTO + response DTO + is kurallari) açıklar.

Geriye Donuk Uyumluluk

V1 (degismedi)

Endpoint: GET /api/v1/users/search
Response item: UserSummaryDto (eski yapi)

V2 (yeni)

Endpoint: GET /api/v2/users/search
Response item: SearchUserV2Dto
Onemli fark: profilePhoto objesi artık dönmez, onun yerine profilePhoto96Url döner.

Endpoint Yapisi

Request

Alan	Tip	Zorunlu	Aciklama
Authorization	string	Evet	`Bearer <JWT>`

Query Parametreleri (`SearchUsersV2QueryDto`)

Parametre	Tip	Zorunlu	Varsayilan	Aciklama
`q`	string	Hayir	`''`	Arama terimi. Bos/whitespace ise random kullanıcı davranisi calisir.
`page`	number	Hayir	`1`	Sayfa numarasi (min `1`).
`limit`	number	Hayir	`5`	Sayfa basi kayit (min `1`, max `100`).
`expertise`	enum	Hayir	`-`	`Expertise` filtresi.

Expertise enum degerleri:

musician
trainer
chef
photographer
designer
stylist
gamer
educator
coach
entertainer
developer
creator

Response

Endpoint, global base response formatinda döner:

{
  "isSuccess": true,
  "statusCode": 200,
  "data": {
    "list": [],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalItems": 0,
      "itemsPerPage": 5,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  },
  "errors": [],
  "timestamp": "2026-02-20T00:00:00.000Z"
}

DTO Yapilari

`SearchUsersV2QueryDto`

type SearchUsersV2QueryDto = {
  q?: string;
  page?: number;   // default: 1, min: 1
  limit?: number;  // default: 5, min: 1, max: 100
  expertise?: Expertise;
};

`SearchUserV2Dto` (response list item)

type SearchUserV2Dto = {
  _id: string;
  username?: string;
  name?: string | null;
  surname?: string | null;
  minutePriceInLiveStream?: number | null;
  expertise?: Expertise | null;
  profilePhoto96Url?: string | null;
  activeLiveStream?: LiveStreamResponseDto | null;
};

`PaginatedResponseDto<SearchUserV2Dto>`

type PaginatedResponseDto<T> = {
  list: T[];
  pagination: {
    currentPage: number;
    totalPages: number;
    totalItems: number;
    itemsPerPage: number;
    hasNextPage?: boolean;
    hasPrevPage?: boolean;
  };
};

Not: activeLiveStream alani LiveStreamResponseDto tipindedir. Bu DTO canli yayin modülündeki standart yayin response sozlesmesini kullanir.

Is Kurallari ve Davranis

q bos ise:

Random kullanıcı listesi döner.
isRegistrationComplete: true filtrelenir.

q dolu ise:

MongoDB Atlas Search (index: user) kullanılır.
username, name, surname alanlarinda autocomplete/fuzzy arama yapilir.

Her iki durumda da:

current user sonuclardan dislanir.
expertise verilirse filtre uygulanır.
Pagination uygulanır (page, limit).

profilePhoto96Url:

Hesaplama kurali: profilePhoto.variants['96'] ?? profilePhoto.url ?? null
profilePhoto objesi responsea dahil edilmez.

activeLiveStream:

Sadece kullanıcının creator oldugu ACTIVE yayinlar dikkate alınir.
Bir kullanıcının birden fazla ACTIVE yayini varsa secim:
- startedAt desc
- createdAt desc
- _id desc
Yayin yoksa null döner.

Ornek Cagri

curl --request GET \
  --url 'https://api.allminelive.com/api/v2/users/search?q=fg&page=1&limit=5&expertise=trainer' \
  --header 'Authorization: Bearer <JWT>'

Ornek Basarili Cevap (200)

{
  "isSuccess": true,
  "statusCode": 200,
  "data": {
    "list": [
      {
        "_id": "698b3452cddbd8c812e1cd9f",
        "username": "fgfg",
        "name": "Gf",
        "surname": "Fgf",
        "minutePriceInLiveStream": 10,
        "expertise": "trainer",
        "profilePhoto96Url": "https://s.allminelive.com/profiles/e58185f3-1bc0-4f78-bc8b-894296fb2a7a/96.webp",
        "activeLiveStream": null
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 1,
      "totalItems": 1,
      "itemsPerPage": 5,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  },
  "errors": [],
  "timestamp": "2026-02-20T08:38:51.978Z"
}

Hata Cevaplari

400

Ornek durumlar:

page < 1 veya limit < 1
limit > 100
gecersiz expertise değeri

401

Authorization token yok/gecersiz

Entegrasyon Notlari (Frontend/Mobile)

V2'de artık profilePhoto objesi gelmeyecegi için UI profilePhoto96Url kullanmalidir.
profilePhoto96Url null olabilecegi için fallback avatar uygulanmalidir.
activeLiveStream null ise "su an yayinda değil" davranisi uygulanmalidir.
V1'e bagli istemciler için endpoint gecisi kontrollu yapilmalidir (/api/v2/users/search).

Kaynak Kod Referanslari

Query DTO: /Users/iberkeugur/baltechventures/allmine-api/src/users/dto/search-users-v2-query.dto.ts
Response DTO: /Users/iberkeugur/baltechventures/allmine-api/src/users/dto/search-user-v2.dto.ts
Controller endpoint: /Users/iberkeugur/baltechventures/allmine-api/src/users/users.controller.ts
Use case: /Users/iberkeugur/baltechventures/allmine-api/src/users/use-cases/search-users-v2.use-case.ts
Strategy (random): /Users/iberkeugur/baltechventures/allmine-api/src/users/use-cases/search-users-v2/random-search-users-v2.strategy.ts
Strategy (atlas): /Users/iberkeugur/baltechventures/allmine-api/src/users/use-cases/search-users-v2/atlas-search-users-v2.strategy.ts
Mapper: /Users/iberkeugur/baltechventures/allmine-api/src/users/use-cases/search-users-v2/search-users-v2.mapper.ts
Active stream lookup: /Users/iberkeugur/baltechventures/allmine-api/src/users/use-cases/search-users-v2/user-active-live-stream-lookup.service.ts
Live stream repo method: /Users/iberkeugur/baltechventures/allmine-api/src/live-stream/repository/live-stream.repository.ts

Users search v2 entegrasyonu