Swift5 API client for XaynBackOfficeSdk

Back Office

The back office is typically used within server-side apps. This SDK acts as a create/read/update/delete interface for anything related to documents.

Document

By document, we refer to a cohesive text, for example a complete news article. However, we only require a simple representation for our system to work. Consisting just of a unique ID, a text snippet and optional properties. The text snippet is ideally a short, meaningful representation of the larger document, reduced to just one paragraph.

Id

The document_id is a unique identifier for a single document. We don't require a specific format, it just needs to comply to the following regexp: ^[a-zA-Z0-9_:@.-]+$.

Snippet

A snippet is a reduced representation of a larger text, for example if the document would be a news article, then its text would be the news article in a pure textual format. In order for our system to work correctly, it is important that the snippet is just the size of one or two paragraphs, and that the snippet's text clearly summarises the larger text. For example, let's take a news article which talks about the effects of inflation. Our snippet could then be: "Inflation worries as prices keep rising. People having budgetary difficulties as a result. Government pressured to take action.". A bad snippet would for example be just taking the very first paragraph of a document, which could sometimes work, but could also lead to: "December 20th 2020. Article written by Jane Doe. On this bright and sunny day, people might forget about their worries sometimes."

Properties

Properties are optional entries for documents, which are usually needed to properly show the document back to the user, when it returns as a personalized document. If for example, you'd wish to integrate a type of carousel view, listing a total of 10 personalized documents in a "for you"-section, then you might choose to display each document as an image and title, with a url to link the user to when pressed. For this, you would need three document properties: image, link and title. You are free to add as many properties as needed.

Auth

The API requires an authentication token when used. Please see further down in this README.md file, or refer to the test included in this SDK's codebase, on how to set this token correctly. \

Overview

This API client was generated by the OpenAPI Generator project. By using the openapi-spec from a remote server, you can easily generate an API client.

• API version: 1.0.0-rc11
• Package version:
• Build package: org.openapitools.codegen.languages.Swift5ClientCodegen

Installation

Carthage

Run carthage update

CocoaPods

Run pod install

Getting started

Setting up the SDK

Our SDK includes a test code page, which simply invokes each existing method. Method invocation examples can always be copied from there.

This SDK has been generated via OpenAPI. The original spec files can be found in our open source git repository. If preferred, you can also generate the SDK yourself using the tooling provided by OpenAPI.

The following code snippet initializes the API using 2 parameters:

• A base_url, which acts as the endpoint for API calls
• An authorization token

let base_url = $URL
let authorizationToken = $TOKEN

XaynBackOfficeSdk.basePath = base_url
XaynBackOfficeSdk.customHeaders["authorizationToken"] = authorizationToken

Creating documents

You can, submit multiple documents at once, with an upper limit of 100 documents per call. If you need to create more documents, then split up your document list into batches of 100 each and then call this method sequentially.

Should one or more documents from a batch fail to be created, then the response will list these documents.

If you pass a document which was already created in the past, then you simply overwrite the old document with the newly provided one. This can only happen if we find the exact same document ID already in our system.

let request = IngestionRequest(documents: [
    IngestedDocument(
        id: "document_A", 
        snippet: "one paragraph about document A", 
        properties: [
            "imageUrl": "https://...",
            "linkUrl": "https://...",
            "datePublished": "...",
            "author": "...",
        ]),
    IngestedDocument(
        id: "document_B", 
        snippet: "one paragraph about document B", 
        properties: [
            "imageUrl": "https://...",
            "linkUrl": "https://...",
            "datePublished": "...",
            "author": "...",
        ])    
])
        
BackOfficeAPI.createDocuments(ingestionRequest: request){ response, error in
    if let error = error else {
        print("\(error)")
        
        return
    }

    // done!
}

Other operations

After documents have been created, you can continue to manage them in different ways.

Please refer to the test file to see some examples, below is a list of available methods:

• deleteDocuments
• deleteDocument
• deleteDocumentProperties
• deleteDocumentProperty
• listDocumentProperties
• getDocumentProperty
• replaceDocumentProperties
• replaceDocumentProperty