The Slate Kit Server is a Web API Server that can host Slate Kit Protocol Independent APIs which can run as both Web APIs and on the CLI ( Command Line ). The server uses Spark Java as the underlying http server. The power of Slate Kits Protocol Independent APIs are that you write them once as normal Kotlin classes with annotations and they are made available on HTTP and conveniently accessible on the command line.
You APIs made available easily on HTTP and CLI
package | slatekit.server |
jar | slatekit.server.jar |
source | slatekit.server |
sample | SampleApp-Server : Full sample application |
apis | Slate Kit APIs : Learn how Slate Kit APIs are designed |
license | free : open-source |
dependencies |
|
![]() |
Check sample app ( containing a full sample code ), the example ( smaller reference on usage ), and source code for more info. |
Goal | Description |
Server Host | The server is designed to simply be a host for existing classes and methods |
Server Features | Pre-built features such as getting version info, diagnostics, error-logging and more |
Server Separation | Decouple server from APIs, which are pure Kotlin classes & Protocol Independent |
Concept | Description |
1. API Containers | All APIs built with Slate Kit are run inside of a API Container. Refer to APIs |
2. Unified Routing | A simple, 3-part hierarchical approach to API routes. Refer to APIs |
3. Unified Requests | A data structure for representing API requests. Refer to APIs |
4. Unified Responses | A data structure for representing API responses. Refer to APIs |
5. Unified Discovery | An approach to API discovery and help docs. Refer to APIs |
Step | About | Docs |
1. Tech | The underlying technology used to build the Http Web API Server | See more |
2. Approach | How the APIs are implemented and hosted in the server |
See more |
3. Examples | Links to several examples of usage from the Sample Apps |
See more |
4. Setup | How to create and run an instance of the server | See more |
5. Options | The configuration options available for the server | See more |
6. Routing | How the routing of Http requests are directed to your APIs | See more |
7. Help | How to enable and view help docs for the API | See more |
8. Security | How to create and run an instance of the server | See more |
9. More | How to configure security and write your own authentication/authorization scheme. | See more |
Built in 100% Kotlin and using Akka-Http and the Slate Components and Utilities.
Tech | Version | Description |
java | 1.8 | JRE |
Kotlin | 1.1.2 | Kotlin sdk |
Spark Java | 2.6 | Http server |
slate.common | - | Using many of the Slate Utilities |
slatekit.core | - | This dependency may be removed soon. |
slatekit.apis | - | Hosts the Slate Kit APIs |
Follows a philosophy of "protocol independent modular APIs" where you embed regular Kotlin classes as APIs to run in the server and/or in the CLI. Our server code marshalls/routes WEB API calls to your APIs. You can optionally annotate your APIs to make more descriptive and configurable.
The server is a container for your existing APIs. For more information see the APIs page
See APIs Back to topThere are multiple examples of using the server to host Web APIS.
example | link | desc |
POKOs | SamplePOKOApi.kt | Plain classes / methods without annotations |
Outputs | SampleTypes1Api.kt | Returning types, lists, maps, objects, etc |
Inputs | SampleTypes2Api.kt | Taking in types, lists, maps, objects, etc |
Smart Types | SampleTypes3Api.kt | Auto-decrypted values and "Smart-Strings" |
Annotations | SampleAnnoApi.kt | Annotations for descriptions and configuration |
Entities | SampleEntityApi.kt | Using built-in entities/orm support |
REST support | SampleRESTApi.kt | Support for REST based routes |
Inheritance | SampleInheritedApi.kt | Using inheritance with APIs |
Filters/Hooks | SampleMiddlewareApi.kt | Enabling middle-ware ( hooks, filters ) for APIs |
Error handling | SampleErrorsApi.kt | Different ways to handle errors |
Roles via Keys | SampleRolesByApp.kt | Security via API keys |
Roles via Roles | SampleRolesByKey.kt | Security via Roles and authorization |
Files | SampleFilesApi.kt | Handling of file types and content |
Refer to SampleAppServer.kt for setup.
Refer to Sample Apps for more info.
You can configure your Slate Server with the environment, other startup info, and APIs you want "embedded", and you are ready to have the server handle REST api calls. You can configure the port, environment, logs, and other settings in application.conf.
// 1: Sample API ( Pure Kotlin annotated classes / methods
@Api(area = "app", name = "tests", verb = "*", protocol = "*")
class SampleApi(context: AppContext): ApiBase(context) {
@ApiAction(desc = "simple greeting", roles = "@parent", verb = "@parent", protocol = "@parent")
fun hello(greeting: String): String {
return "$greeting back"
}
}
// 2: Setup the server with API(s)
val server = Server(
port = 5000,
prefix = "/api/",
info = true,
ctx = AppContext.simple("myapp1"),
apis = listOf(
ApiReg(SampleApi(ctx), false)
)
)
// 3: Run the Server
server.run()
There are various options for configuring the server, with more options coming later.
option | type | sample | desc |
port | Int | 5000 | The port number to run on |
prefix | String | "/api/" | A prefix for each route |
info | Boolean | true | Enable server startup info |
cors | Boolean | false | Enable CORS |
docs | Boolean | false | Enable help docs |
docKey | String | "ABC" | API key for help docs |
apis | List<ApiReg> | List of APIs to host | |
auth | Auth? | null | The auth provider for securing access |
ctx | Context | AppContext.simple("slatekit-server") | The context storing various core dependencies |
Refer to Server.kt for more info.
The server routes WEB API calls to the classes and methods annotated to be publically accessible in your registered APIs. To simplify marshalling calls to your APIs, we have standardized routing conventions. In Slate Kit, you can easily access your apis via Web(http) or command line (CLI ) using a simple routing format. We call this the unified routing format. Refer to APIs for more info.
// 1. app.users.activate via Http GET ( query string )
http://mycompany.com/api/app/users/activate?code=2&phone=123456789&active=true&email=kishore@abc.com
// 2. app.users.activate via Http POST ( json data )
http://mycompany.com/api/app/users/activate
{
code=2, phone=123456789, active=true, email="kishore@abc.com"
}
// 3. CLI: command line syntax
// unified routing format: area.api.action -key=value*
app.users.activate -code=2 -phone=123456789 -active=true -email="kishore@abc.com"
Api discovery is simple with the unified routing formats. All the areas, apis inside areas, and actions inside apis can be easily discovered with the following syntax, and replacing the part with the word help.
Type | Format | Example | Result |
areas | help | http://.../api/help | shows all the areas in system |
apis | area/help | http://.../api/app/help | shows all the apis for the area |
actions | area/api/help | http://.../api/app/users/help | shows all the actions for the api |
action | area/api/action/help | http://.../api/app/users/activate/help | shows signature of the api action |
Security for the APIs is implemented by providing an implementation of the Auth interface to the Server. The APIs can be secured using either API-keys, roles based security and/or using your Auth implementation. The Auth implementation simply validates a Request.
You can optionally annotate, classes and methods with roles and other attributes.
The API guide contains more information on this functionality.
See the API Security
There some interfaces, default implementations and samples of using and building your own auth implemenations. Refer to the sources below
Refer to Auth for more info on the Auth interface
Refer to TokenAuth for a base class support for Auth
Refer to AppAuth for a sample Auth implementation.
There are many more features available. Refer to the API Guide for more info.
Back to top