ruma-api

.gitignore

@@ -0,0 +1,2 @@
+Cargo.lock
+target

.travis.yml

@@ -0,0 +1,9 @@
+language: "rust"
+notifications:
+  email: false
+  irc:
+    channels:
+      - secure: "Zjx9oQaF5PYNCWHIWFAaESlUedHNdXmgT+QO35ETUNtg19w9GrNDAsOWHawuK5wLr8+NicDC0bopJ7fPIbnLz8cL/aluTl8bGlvBf7U+uqvdaxGT2TR0tntnWBzoqhYJVGM2ZspVMOloaJv7jpVdhLtde6w5KhouinaKagQxmX7Mr5ec5r9Xhwv1a72Bk6teLmEqypBmnuuskAD1MOk52piimNzNQIsqs4X+kg+7ZZ+Umx//PHTgh49HMtn/3IdmAZs3xVjrpkgbbQeDi6ynKvxpzS7obizbFB2uQRZedt/+dYVOb2vmVi9WtuNLosIyuwP6rR+A0AYe3pYDoOhUQ3ARb70kVzq9TaXcFXrxH+/Z2LWddmpVOhqDQhBW5S+b2MVXHf5a5yk6QVha68rywd9UPpD4dXsQIfCHZuQ9xLDhOkPbkiVtqSdsiYBjOF+JjFOTKMG7Dx6kACRo74/pwoMWzDDVC0HiSQdesowmoGltB9kKSyT3to651dqGH97iFLBSxsVNYWuAoO/hmLwskbW5EtqC2Crtz+A89KP3es7zsxMKloSOTzrAaYdMSkfDTI1lsHzpdGFMydDEimqRg60XM89CwxkejWPowKErp9kg+8XEh6J8s6W5c814P7oPYdQ9+DgwUr8qi3rrHqdVSa2maK+MLPK+A5riMiqpWqA="
+    use_notice: true
+rust:
+  - "nightly"

Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+authors = ["Jimmy Cuadra <jimmy@jimmycuadra.com>"]
+description = "Core API types for Matrix."
+documentation = "https://docs.rs/ruma-api"
+homepage = "https://github.com/ruma/ruma-api"
+keywords = ["matrix", "chat", "messaging", "ruma"]
+license = "MIT"
+name = "ruma-api"
+readme = "README.md"
+repository = "https://github.com/ruma/ruma-api"
+version = "0.1.0"
+
+[dependencies]
+serde = "0.8.19"
+
+[dev-dependencies]
+ruma-identifiers = "0.5.0"
+serde_derive = "0.8.19"

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Jimmy Cuadra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,14 @@
+# ruma-api
+
+[![Build Status](https://travis-ci.org/ruma/ruma-api.svg?branch=master)](https://travis-ci.org/ruma/ruma-api)
+
+**ruma-api** contains core types used to define the requests and responses for each endpoint in the various [Matrix](https://matrix.org/) API specifications.
+These types can be shared by client and server code for all Matrix APIs.
+
+## Documentation
+
+ruma-api has [comprehensive documentation](https://docs.rs/ruma-api) available on docs.rs.
+
+## License
+
+[MIT](http://opensource.org/licenses/MIT)

src/lib.rs

@@ -0,0 +1,105 @@
+//! Crate ruma_api contains core types used to define the requests and responses for each endpoint
+//! in the various [Matrix](https://matrix.org) API specifications.
+//! These types can be shared by client and server code for all Matrix APIs.
+//!
+//! When implementing a new Matrix API, each endpoint have a type that implements `Endpoint`, plus
+//! any necessary associated types.
+//! An implementation of `Endpoint` contains all the information about the HTTP method, the path and
+//! input parameters for requests, and the structure of a successful response.
+//! Such types can then be used by client code to make requests, and by server code to fulfill
+//! those requests.
+//!
+//! # Example
+//!
+//! ```rust,no_run
+//! # #![feature(proc_macro)]
+//! #
+//! # extern crate ruma_api;
+//! # extern crate ruma_identifiers;
+//! # #[macro_use]
+//! # extern crate serde_derive;
+//! #
+//! # fn main() {
+//! /// PUT /_matrix/client/r0/directory/room/:room_alias
+//! pub mod create {
+//!     use ruma_api;
+//!     use ruma_identifiers::{RoomAliasId, RoomId};
+//!
+//!     /// This API endpoint's body parameters.
+//!     #[derive(Clone, Debug, Deserialize, Serialize)]
+//!     pub struct BodyParams {
+//!         pub room_id: RoomId,
+//!     }
+//!
+//!     /// This API endpoint's path parameters.
+//!     pub struct PathParams {
+//!         pub room_alias: RoomAliasId,
+//!     }
+//!
+//!     /// Details about this API endpoint.
+//!     pub struct Endpoint;
+//!
+//!     impl ruma_api::Endpoint for Endpoint {
+//!         type BodyParams = BodyParams;
+//!         type PathParams = PathParams;
+//!         type QueryParams = ();
+//!         type Response = ();
+//!
+//!         fn method() -> ruma_api::Method {
+//!             ruma_api::Method::Put
+//!         }
+//!
+//!         fn request_path(params: Self::PathParams) -> String {
+//!             format!("/_matrix/client/r0/directory/room/{}", params.room_alias)
+//!         }
+//!
+//!         fn router_path() -> String {
+//!             "/_matrix/client/r0/directory/room/:room_alias".to_string()
+//!         }
+//!     }
+//! }
+//! # }
+
+#![deny(missing_docs)]
+
+extern crate serde;
+
+use serde::{Deserialize, Serialize};
+
+/// HTTP request methods used in Matrix APIs.
+#[derive(Clone, Copy, Debug)]
+pub enum Method {
+    /// DELETE
+    Delete,
+    /// GET
+    Get,
+    /// POST
+    Post,
+    /// PUT
+    Put,
+}
+
+/// An API endpoint.
+pub trait Endpoint {
+    /// Request parameters supplied via the body of the HTTP request.
+    type BodyParams: Deserialize + Serialize;
+
+    /// Request parameters supplied via the URL's path.
+    type PathParams;
+
+    /// Parameters supplied via the URL's query string.
+    type QueryParams;
+
+    /// The body of the response.
+    type Response: Deserialize + Serialize;
+
+    /// Returns the HTTP method used by this endpoint.
+    fn method() -> Method;
+
+    /// Generates the path component of the URL for this endpoint using the supplied parameters.
+    fn request_path(params: Self::PathParams) -> String;
+
+    /// Generates a generic path component of the URL for this endpoint, suitable for `Router` from
+    /// the router crate.
+    fn router_path() -> String;
+}