---

M3O Kotlin (JVM) Client

This is the handcrafted Kotlin client to access APIs on the M3O Platform.

• What is M3O
• Usage
  • Import
  • Initialization / Termination
  • Calling Endpoints
  • Examples
• Extension Functions
• Supported APIs

What is M3O

M3O (website, github repo) is an attempt to build a new public cloud platform with higher level building blocks for the Next generation of developers. M3O is powered by the open source Micro platform and programmable real world Micro Services.

M3O APIs include DB, Cache, Stream, MQ, Events, Functions, App, SMS and more.

Usage

⚠️ This Kotlin client is currently in the beta phase and may experience major and breaking changes.
Therefore I don't recommend to use this client in production at the moment.

Import

To use this library you first have to manually download the .jar file via the Packages tab.
Then import it into your project.

Additionally this client depends on the following dependencies, which you have to import for this library to work properly:

implementation 'io.ktor:ktor-client-core:1.6.8'
implementation 'io.ktor:ktor-client-serialization:1.6.8'
implementation 'org.java-websocket:Java-WebSocket:1.5.3'
implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2'

The built-in Ktor library needs an Ktor HTTP Client. For example

implementation 'io.ktor:ktor-client-apache:1.6.8'

or

implementation 'io.ktor:ktor-client-android:1.6.8'

Initialization / Terminating

Before accessing any API endpoint you have to initialize the library with your M3O API token (if you are missing your token, create one HERE):

M3O.initialize("M3O_API_TOKEN")

Tip for Android development:
To hide your API token in your app I recommend using the Hidden Secrets Gradle Plugin.

---

To check if the library is already initialized you can do

M3O.isInitialized()

and call

M3O.terminate()

to terminate M3O clients and save resources.

Calling endpoints

Every endpoint (which has been added to this Kotlin client) has it's own service object, for example HelloWorldService.

To make any API requests now just call the endpoints via methods on the service object, for example HelloWorldService.call("John").

Examples

Find the examples directory HERE for examples besides the following HelloWorld example.

---

Hello World Call Example:

import com.cyb3rko.m3okotlin.M3O
import com.cyb3rko.m3okotlin.services.HelloWorldService

suspend fun main() {
    M3O.initialize("M3O_API_TOKEN")

    try {
        val response = HelloWorldService.call("John")
        println(response)
    } catch (e: Exception) {
        println(e)
    }
}

Hello World Stream Example:

import com.cyb3rko.m3okotlin.M3O
import com.cyb3rko.m3okotlin.services.HelloWorldService

fun main() {
    M3O.initialize("M3O_API_TOKEN")

    try {
        val socket = HelloWorldService.stream("John", 10) { socketError, response ->
            if (socketError == null) {
                println(response)
            } else {
                println(socketError)
            }
        }
    } catch (e: Exception) {
        println(e)
    }
}

Extension Functions

In addition to calling methods on the service objects there are extension functions for some of the many data classes.
They simplify method calls by calling API functions on data classes.

Check for their availability in the table below.

---

Example:
Log a user in and out again (without extension function)

val mySession = UsersService.login("myPassword", "myEmail").session
UsersService.logout(mySession.id)

(with extension function)

val mySession = UsersService.login("myPassword", "myEmail").session
mySession.logout()       <-- extension function

---

Another Example:
Join a chat room and leave again (without extension function)

val userID = "1234"
val chatRoom = ChatService.list(userID).rooms[0]
ChatService.join(chatRoom.id, userID) { error, response ->
    println(response)
}
ChatService.leave(chatRoom.id, userID)

(with extension function)

val userID = "1234"
val chatRoom = ChatService.list(userID).rooms[0]
chatRoom.join(userID) { error, response ->        <-- extension function
    println(response)
}
chatRoom.leave(userID)       <-- extension function

Supported APIs

Below all supported APIs:

ID	Service	Extension Functions
1	Address	❌
2	Analytics	✅
3	Answers	❌
4	Apps	✅
5	Avatar	❌
6	Bitcoin	❌
7	Cache	❌
8	Carbon	❌
9	Chat	✅
10	Comments	✅
11	Contacts	✅
12	Crypto	✅
13	Currency	✅
14	DB	❌
15	DNS	❌
16	Email	❌
17	Emoji	❌
18	Ethereum	❌
19	EV Chargers	❌
20	Events	❌
21	Files	✅
22	Forex	❌
23	Functions	✅
24	Geocoding	❌
25	GIFs	❌
26	Google	❌
27	Hello World	❌
28	Holidays	✅
29	ID	❌
30	Image	❌
31	IP Geolocation	❌
32	Jokes	❌
33	Lists	✅
34	Location	✅
35	Memegen	✅
36	Minecraft	❌
37	Movies	❌
38	MQ	❌
39	News	❌
40	NFTs	✅
41	Notes	✅
42	OTP	❌
43	Passwords	❌
44	Ping	❌
45	Places
46	Postcode	❌
47	Prayer	❌
48	Prices	✅
49	QR Codes	❌
50	Quran	✅
51	Routing	❌
52	RSS	✅
53	Search	❌
54	Sentiment	❌
55	SMS	❌
56	Space	✅
57	Spam	❌
58	Stocks	❌
59	Stream	✅
60	Sunnah	✅
61	Thumbnail	❌
62	Time	❌
63	Translate	❌
64	Tunnel	❌
65	Twitter	✅
66	URL	❌
67	Users	✅
68	Vehicle	❌
69	Wallet	✅
70	Weather	❌
71	Wordle	❌
72	YouTube	✅