Skip to main content

iOS Managed API Service

info

This documentation is for iOS SDK 2.3.x

Functions​

fetch​

public func fetch(
    name: String,
    relativeUrl: String,
    options: ManagedApiFetchOptions = ManagedApiFetchOptions(),
    onSuccess: @escaping (ManagedApiFetchResponse) -> Void,
    onError: ((Error) -> Void)? = nil
)

public func fetch(
    name: String,
    relativeUrl: String,
    options: ManagedApiFetchOptions = ManagedApiFetchOptions()
) async throws -> ManagedApiFetchResponse

Performs an HTTP request against the Managed API named name. The request URL is the Managed API's baseUrl followed by relativeUrl. Authentication is applied automatically from the Managed API's authentication type (None, Basic, Bearer Token, API Key, OAuth 2.0). For OAuth 2.0 the SDK acquires a token, caches it in the Keychain, refreshes it when it expires and retries once on 401. Whether the consent screen may be shown is governed by options.prompt, see AuthPrompt.

onSuccess is called for every HTTP status; inspect ok / status on the response. onError is called only when the request could not be made: unknown Managed API, missing auth configuration, network failure, a failed or cancelled OAuth flow, or consent being required while prompt is .never. In that last case the error is a DataSapienException with errorCode == DataSapienErrorCodes.INTERACTION_REQUIRED_ERROR_CODE.

Parameters:

  • name: String — Programmatic name of the Managed API.
  • relativeUrl: String — Path appended to baseUrl, e.g. "/me/top/tracks?limit=10". Absolute URLs are rejected.
  • options: ManagedApiFetchOptions — Method, headers and body. Defaults to GET.
  • onSuccess: (ManagedApiFetchResponse) -> Void — Called with the response.
  • onError: ((Error) -> Void)? — Called if the request could not be performed.
DataSapien.getManagedApiService().fetch(
    name: "spotify",
    relativeUrl: "/me/top/tracks?limit=5",
    onSuccess: { response in
        guard response.ok, let json = response.body as? [String: Any] else { return }
        print(json["items"] ?? [])
    },
    onError: { error in
        print("fetch failed: \(error)")
    }
)

getManagedAPIs​

public func getManagedAPIs(
    onSuccess: @escaping ([DataMap]) -> Void,
    onError: ((Error) -> Void)? = nil
)

Returns the key-value pairs of all Managed API definitions currently stored on the device.

Parameters:

  • onSuccess: ([DataMap]) -> Void — Called with the full list of Managed APIs.
  • onError: ((Error) -> Void)? — Called if the operation fails.

getManagedAPI​

public func getManagedAPI(
    name: String,
    onSuccess: @escaping (DataMap?) -> Void,
    onError: ((Error) -> Void)? = nil
)

Retrieves the key-value pairs of a single Managed API by its name. Returns nil if it does not exist. Authentication settings are not included.

Parameters:

  • name: String — Programmatic name of the Managed API.
  • onSuccess: (DataMap?) -> Void — Called with the Managed API key-value pairs or nil.
  • onError: ((Error) -> Void)? — Called if the operation fails.

Classes​

ManagedApiFetchOptions​

public struct ManagedApiFetchOptions {
    public var method: String            // defaults to "GET"
    public var headers: [String: String] // no defaults are added
    public var body: String?             // sent as UTF-8
    public var prompt: AuthPrompt        // defaults to .ifRequired
}

AuthPrompt​

public enum AuthPrompt: String {
    case always = "ALWAYS"          // drop the cached token, always run consent
    case ifRequired = "IF_REQUIRED" // cached → refresh → consent (default)
    case never = "NEVER"            // cached → refresh → INTERACTION_REQUIRED error, no UI
}

Only the OAuth 2.0 Authorization Code grant is affected; other authentication types and grants never show UI.

ManagedApiFetchResponse​

public struct ManagedApiFetchResponse {
    public let status: Int
    public let headers: [String: String]
    public let body: Any?       // parsed JSON when the body is JSON, otherwise the raw String; nil when empty
    public let rawBody: String?
    public var ok: Bool         // true for 2xx
}

ManagedApiAuthType​

public enum ManagedApiAuthType: String {
    case none = "NONE"
    case basic = "BASIC"
    case bearerToken = "BEARER_TOKEN"
    case apiKey = "API_KEY"
    case oauth2 = "OAUTH2"
}

DataMap​

public typealias DataMap = [String: String]