Releases · vimeo/vimeo-networking-java

This is the first alpha version containing the new Kotlin DTOs. These new DTOs are accessible under the new package com.vimeo.networking2. This allows consumers to reference both the old and new DTOs within code without being forced to refactor their code. VimeoClient and supporting infrastructure remain unchanged and use of the new DTOs is not required. In fact, use of the new DTOs is explicitly opt in and as the re-write of VimeoClient is ongoing, they are not completely supported for all requests. The only way to receive the new DTOs is to use a methods on VimeoClient that support providing the Caller<Data_T> interface. These methods include:

VimeoClient.getContent
VimeoClient.getContentSync

With these methods, providing a Caller implementation from GetRequestCaller will give the old Java DTOs, while providing a Caller implementation from MoshiGetRequestCaller will give the new Kotlin DTOs.

Kotlin DTO summary:

Kotlin data classes
Interoperable with Java
Deserialized using moshi instead of stag + gson
Annotated with @Internal if a property or entire DTO can only used by Vimeo and won't be populated for external consumers.

Enums are also provided by the library in the com.vimeo.networking2.enums package. These are accessible only using utility functions on a Kotlin DTO. This contrasts with the Java classes where the enums were fields in the class itself. Instead, the String (or other) value that will be represented by an enum is directly available on the DTO, and a Kotlin extension property (Java utility method) maps the value in the field to its enum counterpart and defaults to an unknown value if the value was not recognized. This alleviates the problem where debugging became difficult when you saw an "unknown" enum value. It was difficult to determine if the consumer was just on an out of date version of the library that didn't support a new enum value or if no value was supplied or if the API was providing an erroneous value. The new enum use looks like this now from Kotlin:

val userBadge = User().badge

val userBadgeTypeString: String = userBadge.rawType
val userBadgeTypeEnum: UserBadgeType = userBadge.type

The documentation on the raw string field will point to the extension function, and the extension function will properly point back to the raw backing field. From Java, things look much different, but it is idiomatic and follows an easy to remember pattern. For classes that have a field representing an enum, the enum can be extracted from the backing field by using the corresponding -Utils class, like this:

final UserBadge userBadge = new User().getBadge();

final String userBadgeTypeString = userBadge.getRawType();
final UserBadgeType userBadgeTypeEnum = UserBadgeUtils.getType(userBadge);

In addition to the enum utils provided, there are also a number of common interfaces that are provided to define functionality of certain DTOs. They are available in the com.vimeo.networking2.common package and are:

Entity: Exists in the legacy version of the library. An interface that defines a class which has an identity, where the unique identifier is provided by a property.
Followable: Also available in the legacy version of the library. This interface is an improved version of the old interface and now only defines that the Metadata property on the implementing DTO has a collection of interactions named FollowableInteractions. The FollowableInteractions interface defines a class that has a property named follow that is of the type UpdateableInteraction.
Interaction: Interactions have common properties and this interface defines them. The options: List<String> property can also be turned into a List<ApiOptionsType> using the enums pattern described above.

Common extensions will also now be present in the library in the package com.vimeo.networking2.extensions. Rather than overload the DTOs with a lot of helper functions, the new version of the library seeks to keep these helper functions separate using extension functions in Kotlin and utility classes in Java. This pattern is followed with respect to enums as described above, however those extensions are uniquely defined in the file containing the DTO. For other extensions, they live in the extensions package.

FollowableExtensions.kt contains Followable.isFollowing and Followable.canFollow Kotlin extension functions on the Followable type (implemented by Channel, Category, Group, and User), which can be used from Java using FollowableUtils.isFollowing(followable) and Followable.canFollow(followable).