OpenAPI and Public REST API | blade47/dub Wiki | doc0

Public

OpenAPI and Public REST API | blade47/dub Wiki | doc0

export const document = createDocument({
  openapi: "3.0.3",
  info: {
    title: "Dub API",
    description:
      "Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.",
    version: "0.0.1",
    contact: {
      name: "Dub Support",
      email: "support@dub.co",
      url: "https://dub.co/support",
    },
    license: {
      name: "AGPL-3.0 license",
      url: "https://github.com/dubinc/dub/blob/main/LICENSE.md",
    },
  },
  servers: [
    {
      url: "https://api.dub.co",
      description: "Production API",
    },
  ],
  paths: {
    ...linksPaths,
    ...analyticsPath,
    ...eventsPath,
    ...tagsPaths,
    ...foldersPaths,
    ...domainsPaths,
    ...trackPaths,
    ...customersPaths,
    ...partnersPaths,
    ...programApplicationsPaths,
    ...discountCodesPaths,
    ...commissionsPaths,
    ...payoutsPaths,
    ...embedTokensPaths,
    ...qrCodePaths,
    ...bountiesPaths,
  },
  components: {
    schemas: {
      LinkSchema,
      LinkTagSchema,
      FolderSchema,
      DomainSchema,
      DiscountCodeSchema,
      webhookEventSchema,
      LinkErrorSchema,
    },
    securitySchemes: {
      token: {
        type: "http",
        description: "Default authentication mechanism",
        scheme: "bearer",
        "x-speakeasy-example": "DUB_API_KEY",
      },
    },
    responses: {
      ...openApiErrorResponsesComponents,
    },
  },
});

import { document } from "@/lib/openapi";
import { NextResponse } from "next/server";
 
export const dynamic = "force-static";
 
export function GET() {
  return NextResponse.json(document, {
    headers: {
      // cache indefinitely till next deployment
      "Vercel-CDN-Cache-Control": "s-maxage=31536000",
      "Cache-Control": "public, max-age=31536000",
    },
  });
}

Path Pattern	HTTP Method	Operation Object	Description / Action
`/links`	`post`	`createLink`	Create a new link
`/links`	`get`	`getLinks`	Retrieve a paginated list of links
`/links/count`	`get`	`getLinksCount`	Retrieve the total count of links
`/links/info`	`get`	`getLinkInfo`	Retrieve metadata/info for a specific link
`/links/{linkId}`	`patch`	`updateLink`	Update an existing link by identifier
`/links/{linkId}`	`delete`	`deleteLink`	Delete a link by identifier
`/links/bulk`	`post`	`bulkCreateLinks`	Bulk create multiple links
`/links/bulk`	`patch`	`bulkUpdateLinks`	Bulk update multiple links
`/links/bulk`	`delete`	`bulkDeleteLinks`	Bulk delete multiple links
`/links/upsert`	`put`	`upsertLink`	Upsert a link resource

export const getLinks: ZodOpenApiOperationObject = {
  operationId: "getLinks",
  "x-speakeasy-name-override": "list",
  "x-speakeasy-pagination": {
    type: "offsetLimit",
    inputs: [
      { name: "page", in: "parameters", type: "page" },
      { name: "pageSize", in: "parameters", type: "limit" },
    ],
    outputs: { results: "$" },
  },
  summary: "List all links",
  description: "Retrieve a paginated list of links for the authenticated workspace.",
  requestParams: { query: getLinksQuerySchemaBase },
  responses: {
    "200": {
      description: "A list of links",
      content: { "application/json": { schema: z.array(LinkSchema) } },
    },
    ...openApiErrorResponses,
  },
  tags: ["Links"],
  security: [{ token: [] }],
};

export const getLinkInfo: ZodOpenApiOperationObject = {
  operationId: "getLinkInfo",
  "x-speakeasy-name-override": "get",
  summary: "Retrieve a link",
  description: "Retrieve the info for a link.",
  requestParams: { query: getLinkInfoQuerySchema },
  responses: {
    "200": {
      description: "The retrieved link",
      content: { "application/json": { schema: LinkSchema } },
    },
    ...openApiErrorResponses,
  },
  tags: ["Links"],
  security: [{ token: [] }],
};

export const getLinksCount: ZodOpenApiOperationObject = {
  operationId: "getLinksCount",
  "x-speakeasy-name-override": "count",
  summary: "Retrieve links count",
  description: "Retrieve the number of links for the authenticated workspace.",
  requestParams: { query: getLinksCountQuerySchema },
  responses: {
    "200": {
      description: "A list of links",
      content: {
        "application/json": {
          schema: z.number().meta({ description: "The number of links matching the query." }),
        },
      },
    },
    ...openApiErrorResponses,
  },
  tags: ["Links"],
  security: [{ token: [] }],
};

export const GET = withWorkspace(
  async ({ headers, searchParams, workspace, session }) => {
    const filters = getLinksQuerySchemaExtended.parse(searchParams);
 
    const { folderIds } = await validateLinksQueryFilters({
      ...filters,
      workspace,
      sessionUserId: session.user.id,
    });
 
    const response = await getLinksForWorkspace({
      ...filters,
      workspaceId: workspace.id,
      folderIds,
      sortBy:
        workspace.totalLinks > SORTABLE_LINKS_LIMIT
          ? "createdAt"
          : filters.sortBy,
      searchMode:
        workspace.totalLinks > MEGA_WORKSPACE_LINKS_LIMIT ? "exact" : "fuzzy",
    });
 
    return NextResponse.json(response, {
      headers,
    });
  },
  {
    requiredPermissions: ["links.read"],
  },
);

export const POST = withWorkspace(
  async ({ req, headers, session, workspace }) => {
    if (workspace) {
      throwIfLinksUsageExceeded(workspace);
    }
 
    const body = await createLinkBodySchemaAsync.parseAsync(
      await parseRequestBody(req),
    );
 
    if (!session) {
      const ip = req.headers.get("x-forwarded-for") || LOCALHOST_IP;
      await assertRateLimit({
        policy: RATELIMIT_POLICIES.anonymousLinkCreate,
        identifier: ip,
      });
    }
 
    const { link, error, code } = await processLink({
      payload: body,
      workspace,
      ...(session && { userId: session.user.id }),
    });
 
    if (error != null) {
      throw new DubApiError({
        code: code as ErrorCodes,
        message: error,
      });
    }
 
    try {
      const response = await createLink(link);
 
      if (response.projectId && response.userId) {
        waitUntil(
          sendWorkspaceWebhook({
            trigger: "link.created",
            workspace,
            data: linkEventSchema.parse(response),
          }),
        );
      }
 
      return NextResponse.json(response, {
        headers,
      });
    } catch (error) {
      throw new DubApiError({
        code: "unprocessable_entity",
        message: error.message,
      });
    }
  },
  {
    requiredPermissions: ["links.write"],
  },
);

export async function GET(req: NextRequest) {
  try {
    const origin = req.headers.get("origin");
    const corsHeaders = {
      "Access-Control-Allow-Methods": "GET",
      "Access-Control-Allow-Headers": "Content-Type",
    };
 
    if (origin && origin.endsWith(".dub.co")) {
      corsHeaders["Access-Control-Allow-Origin"] = origin;
    }
 
    const { url } = getUrlQuerySchema.parse({
      url: req.nextUrl.searchParams.get("url"),
    });
 
    await ratelimitOrThrow(req, "metatags");
 
    const metatags = await getMetaTags(url);
 
    return NextResponse.json(
      {
        ...metatags,
        poweredBy: "Dub - The Modern Link Attribution Platform",
      },
      {
        headers: {
          ...corsHeaders,
          "Cache-Control": "public, max-age=300",
          "Vercel-CDN-Cache-Control":
            "s-maxage=3600, stale-while-revalidate=86400",
        },
      },
    );
  } catch (error) {
    return handleAndReturnErrorResponse(error);
  }
}

export async function GET(req: NextRequest) {
  try {
    const { url, domain } = getUrlQuerySchema
      .and(getDomainQuerySchema)
      .parse(getSearchParams(req.url));
 
    await ratelimitOrThrow(req, "iframeable");
 
    const iframeable = await isIframeable({ url, requestDomain: domain });
 
    return NextResponse.json({ iframeable });
  } catch (error) {
    return handleAndReturnErrorResponse(error);
  }
}

Schema Identifier	Zod Definition Source	Description / Data Type
`AnalyticsCount`	`analyticsResponse.count`	Aggregate count metrics
`AnalyticsTimeseries`	`analyticsResponse.timeseries`	Array of timeseries data points
`AnalyticsContinents`	`analyticsResponse.continents`	Array of continent-level breakdowns
`AnalyticsCountries`	`analyticsResponse.countries`	Array of country-level breakdowns
`AnalyticsRegions`	`analyticsResponse.regions`	Array of region/state breakdowns
`AnalyticsCities`	`analyticsResponse.cities`	Array of city-level breakdowns
`AnalyticsDevices`	`analyticsResponse.devices`	Array of device type breakdowns
`AnalyticsBrowsers`	`analyticsResponse.browsers`	Array of browser breakdowns
`AnalyticsOS`	`analyticsResponse.os`	Array of operating system breakdowns
`AnalyticsTriggers`	`analyticsResponse.triggers`	Array of tracking trigger breakdowns
`AnalyticsEventNames`	`analyticsResponse.event_names`	Array of custom event name breakdowns
`AnalyticsReferers`	`analyticsResponse.referers`	Array of referer breakdowns
`AnalyticsRefererUrls`	`analyticsResponse.referer_urls`	Array of specific referer URL breakdowns
`AnalyticsTopLinks`	`analyticsResponse.top_links`	Array of top-performing links
`AnalyticsTopUrls`	`analyticsResponse.top_urls`	Array of top destination URLs

Path Pattern	HTTP Method	OpenAPI Object Ref	Purpose
`/domains`	`POST`	`createDomain`	Add and configure a new custom or `.dub.link` domain
`/domains`	`GET`	`listDomains`	Retrieve all domains associated with the workspace
`/domains/{slug}`	`PATCH`	`updateDomain`	Update domain settings, URLs, or metadata
`/domains/{slug}`	`DELETE`	`deleteDomain`	Delete or archive an existing domain
`/domains/register`	`POST`	`registerDomain`	Register a new domain through the provider
`/domains/status`	`GET`	`checkDomainStatus`	Check DNS and verification status for a domain

Path Pattern	HTTP Method	OpenAPI Operation ID / Name Override	Purpose
`/partners`	`POST`	`createPartner`	Create a new partner
`/partners`	`GET`	`listPartners`	List all partners
`/partners/links`	`POST`	`createPartnerLink`	Create a partner link
`/partners/links`	`GET`	`retrievePartnerLinks`	Retrieve partner links
`/partners/links/upsert`	`PUT`	`upsertPartnerLink`	Upsert a partner link
`/partners/analytics`	`GET`	`retrievePartnerAnalytics` (`analytics`)	Retrieve partner analytics data
`/partners/ban`	`POST`	`banPartner`	Ban a partner
`/partners/deactivate`	`POST`	`deactivatePartner`	Deactivate a partner

Ecosystem Route Path	HTTP Method	Request Schema	Response Content Type / Schema
`/customers`	`GET`	`getCustomers` query schema	`application/json` (Array of customers)
`/customers/{id}`	`GET`	`getCustomer` path param	`application/json` (Customer object)
`/customers/{id}`	`PATCH`	`updateCustomer` body schema	`application/json` (Customer object)
`/customers/{id}`	`DELETE`	`deleteCustomer` path param	`application/json` (Deleted confirmation)
`/tokens/embed/referrals`	`POST`	Referrals embed body schema	`application/json` (Embed token)
`/qr`	`GET`	`getQRCodeQuerySchema`	`image/png` (String binary)

import { NextRequest, NextResponse } from "next/server";
import { parse } from "./utils/parse";
 
export function ApiMiddleware(req: NextRequest) {
  const { fullPath } = parse(req);
 
  // redirect to dub.co for /metatags
  if (fullPath.startsWith("/metatags")) {
    return NextResponse.redirect("https://dub.co", {
      status: 301,
    });
  }
  // Note: we don't have to account for paths starting with `/api`
  // since they're automatically excluded via our middleware matcher
  return NextResponse.rewrite(new URL(`/api${fullPath}`, req.url));
}

Hostname or Path Pattern	Interception Condition	Middleware Handler / Action	Target Destination / Behavior
`app.dub.co`	`isAppHostname(domain)`	`AppMiddleware(req)`	Application dashboard routing
`api.dub.co`	`API_HOSTNAMES.has(domain)`	`ApiMiddleware(req)`	Rewrites to `/api${fullPath}`
`/stats/*`	`path.startsWith("/stats/")`	`NextResponse.rewrite`	Rewrites to `/[domain]/[key]/stats`
`/.well-known/*`	`path.startsWith("/.well-known/")`	`NextResponse.rewrite`	Rewrites to `/wellknown/[domain]/[file]`
`dub.sh`	`domain === "dub.sh" && DEFAULT_REDIRECTS[key]`	`NextResponse.redirect`	Redirects to default URL mapping
Admin Hostnames	`ADMIN_HOSTNAMES.has(domain)`	`AdminMiddleware(req)`	Administrative interface routing
Partner Hostnames	`PARTNERS_HOSTNAMES.has(domain)`	`PartnersMiddleware(req)`	Partner ecosystem routing
Valid URLs	`isValidUrl(fullKey)`	`CreateLinkMiddleware(req)`	On-the-fly link creation flow