rest
Identifies a org.mashupbots.socko.rest.RestRequest parameter validation
Binds a value in the request class to a value in the request body
Binds a value in the request class to a value in the request body
case class(context: RestRequestContext, @RestBody() pet: Pet) extends RestRequest
REST config
Parameter meta data
Our categorization of the type of the field
Type of the field
For object fields that needs to be deserialized, this is the Java class of the field.
For other categories of deserialization (primitive, bytes, etc) this is set to None and not used.
Flag to indicate if this field is required or not. If not, it must be of type Option[_]
Parameter that binds to a value in the header
Parameter that binds to a value in the header
Name of the request parameter
Short description of the parameter
Serialize a byte array (hint: this does not do much!)
Serialize a byte array (hint: this does not do much!)
Name of field used to store response data.
For case class StringResponse(context: RestResponseContext, data: String) extends RestResponse,
the term is data.
Mirror used to extract the value of responseDataTerm from the response object
Serialize a byte sequence (hint: this does not do much!)
Serialize a byte sequence (hint: this does not do much!)
Name of field used to store response data.
For case class StringResponse(context: RestResponseContext, data: String) extends RestResponse,
the term is data.
Mirror used to extract the value of responseDataTerm from the response object
Serializes data into a byte array
Details a HTTP error
Details a HTTP error
HTTP response status code
Text description of the error
Binds a value in the request class to a value in the request header
Binds a value in the request class to a value in the request header
case class(context: RestRequestContext, @RestHeader() rows: Int) extends RestRequest
REST config
Parameter meta data
Type of the field
Flag to indicate if this field is required or not. If not, it must be of type Option[_]
Parameter that binds to a value in the header
Parameter that binds to a value in the header
Name of the request parameter
Short description of the parameter
Name of the header field. If empty (default), then the header field name
is assumed to be the same as name.
Specifies that a comma-separated list of values can be passed.
Defaults to false.
Input validation
Class to denote that no serialization is required because it will be custom handled by the REST processing actor
Encapsulates common aspects of non void serializers
Serialize an object into a UTF-8 JSON byte array
Serialize an object into a UTF-8 JSON byte array
If the data is of type Option[] and the value is None, an empty array will be returned.
Type of the data to serialize
Name of field used to store response data.
For case class StringResponse(context: RestResponseContext, data: String) extends RestResponse,
the term is data.
Mirror used to extract the value of responseDataTerm from the response object
Binds a value in the request class to a value in the request uri path
Binds a value in the request class to a value in the request uri path
/path/{Id}
case class(context: RestRequestContext, @RestPath() id: Int) extends RestRequestREST configuration
Parameter meta data
Type of the field
Index of the value of the field in array of path segments
Parameter that binds to a value in the path
Parameter that binds to a value in the path
Name of the request parameter
Short description of the parameter
Input validation
Encapsulates a path segment
Encapsulates a path segment
// '{Id}' PathSegment("Id", true) // 'user' PathSegment("user", false)
Name of the variable or static segment
Flag to denote if this segment is variable and is intended to be bound to a variable or not. If not, it is a static segment
Serialize a primitive into a UTF-8 JSON byte array
Serialize a primitive into a UTF-8 JSON byte array
If the data is of type Option[] and the value is None, an empty array will be returned.
Type of the data to serialize
Name of field used to store response data.
For case class StringResponse(context: RestResponseContext, data: String) extends RestResponse,
the term is data.
Mirror used to extract the value of responseDataTerm from the response object
Path, QueryString and Header params must bind to a primitive.
Path, QueryString and Header params must bind to a primitive. This trait holds their common functions.
Parameter that binds to a value in the query string
Parameter that binds to a value in the query string
Name of the request parameter
Short description of the parameter
Name of the query string field. If empty (default), then the query string field
name is assumed to be the same as name.
Specifies that a comma-separated list of values can be passed
Defaults to false.
Input validation
Binds a value in the request class to a value in the request query string
Binds a value in the request class to a value in the request query string
/path?rows=1 case class(context: RestRequestContext, @RestQuery() rows: Option[Int]) extends RestRequest
REST config
Parameter meta data
Type of the field
Flag to indicate if this field is required or not. If not, it must be of type Option[_]
Identifies a org.mashupbots.socko.rest.RestRequest parameter binding
Binding of a request value
Exception raised during the process of deserializing and dispatching a request
Exception raised during the process of deserializing and dispatching a request
Error message
Configuration for REST handler
Configuration for REST handler
This can also be loaded from an externalized AKKA configuration file. For example:
rest-config {
# The version of your API. Required.
api-version="1.0"
# Root path to your API with the scheme, domain and port. Required.
# This is the path as seen by the end user and not from on the local server.
root-api-url=http://yourdomain.com/api
# Swagger definition version. Defaults to `1.1` if setting is omitted.
swagger-version="1.1"
# Path segments to group your APIs into Swagger resources. For exmaple, `/pet` is one resource
# while `/user` is another. Default is `1` which refers to the first relative path segment.
swagger-api-grouping-path-segment=1
# Number of seconds before a request is timed out.
# Defaults to `60` seconds if setting is omitted.
request-timeout-seconds=60
# Number of seconds before a SockoEvent is removed from the cache and cannot be accessed by
# your actor. Defaults to `5` if setting is omitted.
socko-event-cache-timeout-seconds=5
# Maximum number of workers per RestHandler
# Defaults to 100 if setting is omitted.
max-worker-count=100
# Reschedule a message for processing again using this delay when max worker count has been reached.
# Defaults to 500 if setting is omitted
max-worker-reschedule-milliseconds=500
# Determines if the message from runtime exceptions caught during handing of a REST request is returned
# to the caller in addition to the HTTP status code. Values are: `Never`, `BadRequestsOnly`,
# `InternalServerErrorOnly or `All`.
# Defaults to `Never` if setting is omitted
report-runtime-exception=Never
# Swagger details overriding the details loaded via reflection
overrides {
classes = [{
name = TestOverrideClass
description = Test Override Description
properties = [{
name = Property1
type = Int
description = Description of Property 1
required = true
}]
}]
}
}can be loaded as follows:
object MyRestHandlerConfig extends ExtensionId[RestConfig] with ExtensionIdProvider { override def lookup = MyRestHandlerConfig override def createExtension(system: ExtendedActorSystem) = new RestConfig(system.settings.config, "rest-config") } val myRestConfig = MyRestHandlerConfig(actorSystem)
the version of your API
Root path to your API with the scheme, domain and port. For example, http://yourdomain.com/api.
This is the path as seen by the end user and not from on the local server.
Swagger definition version
Path segments to group APIs by. Default is 1 which refers to the first
relative path segment.
For example, the following will be grouped under the /pets because the the share pets in the 1st path
segment.
/pets
/pets/{petId}
/pets/findByIdNumber of seconds before a request is timed out. Make sure that your processor
actor responds within this number of seconds or throws an exception. Defaults to 60 seconds.
Number of seconds before a org.mashupbots.socko.events.SockoEvent is
removed from the cache and cannot be accessed by the REST processor. Once the REST processor has access to
the org.mashupbots.socko.events.SockoEvent, its expiry from the cache does not affect usability. The cache
is just used as a means to pass the event. Defaults to 5 seconds.
Maximum number of workers per org.mashupbots.socko.rest.RestHandler.
Reschedule a message for processing again using this delay when max worker count has been reached.
Determines if the message from runtime exceptions caught during handing of a REST request is returned to the caller in addition to the HTTP status code.
Two types of exceptions are raised: 400 Bad Requests and 500 Internal Server Error. If turned on, the
message will be return in the response and the content type set to text/plain; charset=UTF-8.
Used to override the documentation associated with one or more classes, which will otherwise be created via reflection. The format of the override within application.conf is as follows:
overrides {
classes = [{
name = <class name>
description = <description>
properties = [{
name = <property name>
type = <property type>
description = <property description>
required = <true or false>
range {min=<min>, max=<max>} or list = [<value1>, <value2>, ... <valueN>] (optional)
}]
}]
}where class name = name of class without package (e.g. String instead of java.lang.String) description = brief text description of class property name = name of property within class property type = type of property (int, String, CustomClassName, etc) property description = brief text description of property required = true if property is required, else false if it is optional range or list = allowed values, or disregard if no allowable values are to be documented
Error with your REST definition
The HTTP method and path to a REST operation
The HTTP method and path to a REST operation
HTTP method. e.g. GET.
Root path of the REST service. e.g. /api.
Path relative to the rootPath for the REST operation
The initial processing point for incoming requests.
The initial processing point for incoming requests. It farms requests out to worker.
Capacity control is implemented here. The maximum number of workers is limited. When the limit is reached, messages are rescheduled for processing.
FSM data for org.mashupbots.socko.rest.RestHandler
FSM states for org.mashupbots.socko.rest.RestHandler
Message that can be sent to a RestHandler to retrieve the current number of workers
Processes a HTTP REST request.
Processes a HTTP REST request.
Processing steps:
registry and the actor that will be used to process the request
FSM data for org.mashupbots.socko.rest.RestHttpWorker
FSM states for org.mashupbots.socko.rest.RestHttpWorker
Meta data to describe REST model classes.
Meta data to describe REST model classes. The trait is expected to be implemented by companion objects.
For example:
case class Pet(tags: Array[Tag], id: Long, category: Category, status: String, name: String, photoUrls: Array[String]) object Pet extends RestModelMetaData { val modelProperties = Seq( RestPropertyMetaData("status", "pet status in the store", Some(AllowableValuesList(List("available", "pending", "sold"))))) }
Exception raised during if a matching operation cannot be found
Exception raised during if a matching operation cannot be found
Error message
A REST operation processes data in the following manner:
A REST operation processes data in the following manner:
Meta data describing the bindings
HTTP method and path unique to this operation
Deserializes incoming data into a org.mashupbots.socko.rest.RestRequest
Serializes a org.mashupbots.socko.rest.RestResponse class to send to the client
Exception raised during the process of a request
Exception raised during the process of a request
Error message
Describes a property in this model class
Describes a property in this model class
Name of field
Brief description of the field
Optional allowable list of values or range of values
Binds a org.mashupbots.socko.rest.RestRequest, org.mashupbots.socko.rest.RestResponse and a processor actor to an end point.
Binds a org.mashupbots.socko.rest.RestRequest, org.mashupbots.socko.rest.RestResponse and a processor actor to an end point.
This is implemented as an abstract class rather than a trait so that it is easier to override methods and values.
Collection org.mashupbots.socko.rest.RestOperations that will be used to process incoming requests.
Collection org.mashupbots.socko.rest.RestOperations that will be used to process incoming requests.
REST operations that will be used for processing requests
Swagger API documentation
REST configuration
A request to be processed by a REST processing actor
Provides context to a REST request.
Provides context to a REST request. Contains request meta-data.
UUID for this rest request/response pair
HTTP URL at which the request was received
HTTP request headers
Number of seconds before this request times out
Deserializes incoming request data into a org.mashupbots.socko.rest.RestRequest
Deserializes incoming request data into a org.mashupbots.socko.rest.RestRequest
REST config
Request class
Constructor to call when instancing the request class
Bindings to extract values form the request data. The values will be passed into the requestConstructor to instance the request class.
The result of processing a org.mashupbots.socko.rest.RestRequest
Context of the REST response.
Context of the REST response. Contains response meta-data.
The request context to which this is a response
HTTP status
HTTP response headers
Serialized outgoing data from a org.mashupbots.socko.rest.RestResponse
Serialized outgoing data from a org.mashupbots.socko.rest.RestResponse
REST configuration
Response class symbol
Data type specific serializer
Swagger API declaration
Generated Swagger API documentation
Generated Swagger API documentation
Map of path and swagger JSON associated with the path
API error refers to the HTTP response status code and its description
API operation refers to a specific HTTP operation that can be performed for a path
API parameter refers to a path, body, query string or header parameter in a org.mashupbots.socko.rest.SwaggerApiOperation
API path refers to a specific path and all the operations for that path
A swagger model complex data type.
A swagger model complex data type. This is built from reflection of the passed class type
Unique id
description
List of properties
A swagger model complex data type's properties
A swagger model complex data type's properties
Swagger data type
Description of the property
Boolean to indicate if the property is required. If None, false is assumed.
Optional allowable list or range of values
Only applicable for containers. Defines the data type of items in a container.
For primitives, it is "type":"string". For complex types, it is "ref":"Category".
Registry of swagger models.
Registry of swagger models. Makes sure that we don't output a model more than once.
Runtime Mirror
Model overrides to be used
Swagger resource listing
Describes a specific resource in the resource listing
Serializes a void response.
Serializes a void response.
This is a placeholder because with void, there is no data to serialize.
Companion object
Convenience object to read the overrides from the configuration file and reformat them for use in Socko
HTTP method supported by org.mashupbots.socko.rest.RestHandler
Factory to parse a string into a path segment
Companion class
Indicates if we want to return a runtime exception message to the caller
Indicates if we want to return a runtime exception message to the caller
Depending on your security requirements, you may wish to turn off errors in production but turn then on in development.
No error messages are returned by default (Never).
Companion object
Companion object
Factory to instance a registry
Companion object
Companion object
Cache of SockoEvents so REST processor actors can access it for custom request deseralization and custom response seralization.
Cache of SockoEvents so REST processor actors can access it for custom request deseralization and custom response seralization.
It is NOT passes as part of org.mashupbots.socko.rest.RestRequest because we want org.mashupbots.socko.rest.RestRequest to be fully immutable so that it can optionally be sent to remote actors for processing.
Companion object
Denotes the type of org.mashupbots.socko.events.SockoEvent that triggered this REST request
Companion object
Companion object
Companion object
Companion object
Companion object
Scala to Swagger conversion
Companion object
Identifies a org.mashupbots.socko.rest.RestRequest parameter validation
Note that
valueTypemust be in the constructor otherwise it will not be be json serialized.