Skip to main content

Introducing Idiomatic Code Samples for Models, Enums, and Errors

· 4 min read

Our SDKs are now more AI ready than ever. Model reference docs now show idiomatic, language-specific code samples, complete with imports, instead of serialized payloads. They cover how to initialize a structure, reference an enum value, and catch errors across all seven SDK languages.

What's New?​

Previously, the Example block on a model reference always showed a serialized JSON/XML payload, regardless of the type. That's a good wire example, but a poor "how do I use this in code" example. You never construct an error type by hand, and you reference an enum value rather than building a JSON object. The Example block is now tailored to the kind of type it describes. AI tools can pull these idiomatic samples directly from the portal using the AI Assist Menu.

Idiomatic initialization code for structures​

Structure models now show language-native initialization code (for example, new Foo { ... }) instead of a JSON payload, along with the import or using statements the snippet depends on, so the example is ready to paste and run rather than just illustrative. When no code sample can be rendered, the docs fall back to the JSON/XML payload as before, so nothing is lost.

import com.paypal.sdk.models.OrderTrackerItem;
import com.paypal.sdk.models.OrderTrackerRequest;
import com.paypal.sdk.models.ShipmentCarrier;
import java.util.Arrays;

OrderTrackerRequest orderTrackerRequest = new OrderTrackerRequest.Builder(
    "capture_id2"
)
.trackingNumber("tracking_number8")
.carrier(ShipmentCarrier.ECHO)
.carrierNameOther("carrier_name_other2")
.notifyPayer(false)
.items(Arrays.asList(
        new OrderTrackerItem.Builder()
            .name("name8")
            .quantity("quantity4")
            .sku("sku6")
            .url("url2")
            .imageUrl("image_url4")
            .build(),
        new OrderTrackerItem.Builder()
            .name("name8")
            .quantity("quantity4")
            .sku("sku6")
            .url("url2")
            .imageUrl("image_url4")
            .build()
    ))
.build();

Value references for enums​

Enum models now show how to reference an element the idiomatic way for each language (for example, Foo foo = Foo.VALUE;) instead of a bare example value. Every language gained these new enum examples with correct language-native syntax.

import { CvvCode } from 'paypal-server-sdklib';

const cvvCode = CvvCode.CvvP;

Error-handling examples for error types​

Error and exception types now show a try/catch example demonstrating how to handle the error an endpoint throws, which is far more useful than constructing the type yourself. The error's properties are already described elsewhere in the documentation, so the example focuses on how to catch it. For SDKs that don't throw on HTTP error status codes (configurable in PHP, Python, and Ruby), the sample adapts: it's omitted where it wouldn't apply, and PHP instead shows the ApiResponse-based typed-error sample when error type mapping is enabled.

try {
    // make the API call
} catch (SearchErrorException $exp) {
    echo 'Caught SearchErrorException:', $exp;
} catch (ApiException $exp) {
    echo 'Caught ApiException:', $exp;
}

Full code samples on Model pages​

The same examples flow through to the Model pages in the developer portal. Developers can read about a model and copy working initialization, enum-reference, or error-handling code from the same page, without switching context.

All of this works across the seven SDK languages: C#, Java, Go, Python, Ruby, PHP, and TypeScript.

Why This Matters​

Previously, developers and AI tools often had to infer how to initialize a model, set an enum value, or handle a failed API call from a serialized payload that didn't reflect real code. That guesswork led to snippets that didn't compile or that missed important error cases.

With this update:

  • Structures, enums, and error types each come with the right kind of idiomatic, copy-ready example.
  • Error handling is shown explicitly with try/catch, so the expected error types and usage are clear.
  • AI tools reading the SDK docs and Model pages have complete, accurate examples to ground their answers in.
  • Developers spend less time piecing together correct usage and more time building.