-
Notifications
You must be signed in to change notification settings - Fork 3
Home
Mikael Sand edited this page Jul 26, 2015
·
1 revision
Welcome to the OpenDemocracy.fi wiki!
The current version of the app explores how simply we can build a range voting software using modern tech.
Another approach we've been thinking of is reusing the data model from the old version. We've started work on an Swagger v2.0 spec which can now be used to generate REST api servers and clients in various languages and frameworks.
Here is a current work-in-progress of the swagger spec, view/edit it with http://editor.swagger.io/#/ Check out the swagger tool chain to generate a server, and point the Swagger UI demo http://petstore.swagger.io/ to your spec and host uri to test it.
{
"swagger":"2.0",
"info":{
"version":"1.0.0",
"title":"Open Democracy",
"description":"An API that allows range and trust based transitive voting",
"contact":{
"name":"OpenDemocracy.fi Team",
"email":"team@opendemocracy.fi",
"url":"http://opendemocracy.fi"
},
"license":{
"name":"MIT",
"url":"http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT"
}
},
"host":"opendemocracy.fi",
"basePath":"/api",
"schemes":[
"http"
],
"consumes":[
"application/json"
],
"produces":[
"application/json"
],
"paths":{
"/proposition":{
"get":{
"description":"Returns all propositions from the system that the user has access to",
"operationId":"findPropositions",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"tags",
"in":"query",
"description":"tags to filter by",
"required":false,
"type":"array",
"items":{
"type":"string"
},
"collectionFormat":"csv"
},
{
"name":"categories",
"in":"query",
"description":"categories to filter by",
"required":false,
"type":"array",
"items":{
"type":"string"
},
"collectionFormat":"csv"
},
{
"name":"limit",
"in":"query",
"description":"maximum number of results to return",
"required":false,
"type":"integer",
"format":"int32"
}
],
"responses":{
"200":{
"description":"proposition response",
"schema":{
"type":"array",
"items":{
"$ref":"#/definitions/proposition"
}
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"post":{
"description":"Creates a new proposition in the system. Duplicates are allowed",
"operationId":"addProposition",
"produces":[
"application/json"
],
"parameters":[
{
"name":"proposition",
"in":"body",
"description":"Proposition to add to the system",
"required":true,
"schema":{
"$ref":"#/definitions/proposition"
}
}
],
"responses":{
"200":{
"description":"proposition response",
"schema":{
"$ref":"#/definitions/proposition"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/proposition/{id}":{
"get":{
"description":"Returns a proposition based on a single ID",
"operationId":"findPropositionById",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to fetch",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"200":{
"description":"proposition response",
"schema":{
"$ref":"#/definitions/proposition"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"delete":{
"description":"deletes a single proposition based on the ID supplied",
"operationId":"deleteProposition",
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to delete",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"204":{
"description":"proposition deleted"
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/proposition/{id}/option":{
"get":{
"description":"Returns all options from the system that the user has access to",
"operationId":"findOptions",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to show options for",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"limit",
"in":"query",
"description":"maximum number of results to return",
"required":false,
"type":"integer",
"format":"int32"
}
],
"responses":{
"200":{
"description":"option response",
"schema":{
"type":"array",
"items":{
"$ref":"#/definitions/option"
}
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"post":{
"description":"Creates a new option in the system.",
"operationId":"addOption",
"produces":[
"application/json"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to show options for",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"option",
"in":"body",
"description":"Option to add to the system",
"required":true,
"schema":{
"$ref":"#/definitions/option"
}
}
],
"responses":{
"200":{
"description":"option response",
"schema":{
"$ref":"#/definitions/option"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/proposition/{id}/option/{optionId}":{
"get":{
"description":"Returns a option based on a single ID",
"operationId":"findOptionById",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to fetch",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"optionId",
"in":"path",
"description":"ID of option to fetch",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"200":{
"description":"option response",
"schema":{
"$ref":"#/definitions/option"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"delete":{
"description":"deletes a single option based on the ID supplied",
"operationId":"deleteOption",
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"optionId",
"in":"path",
"description":"ID of option to delete",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"204":{
"description":"option deleted"
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/proposition/{id}/option/{optionId}/vote":{
"get":{
"description":"Returns votes based on a single ID",
"operationId":"findVotesById",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to fetch",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"optionId",
"in":"path",
"description":"ID of option to fetch",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"200":{
"description":"vote response",
"schema":{
"type":"array",
"items":{
"$ref":"#/definitions/vote"
}
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"post":{
"description":"Creates a new vote in the system. Duplicates are allowed",
"operationId":"addVote",
"produces":[
"application/json"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of proposition to vote in",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"optionId",
"in":"path",
"description":"ID of option to vote for",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"vote",
"in":"body",
"description":"Vote to add to the system",
"required":true,
"schema":{
"$ref":"#/definitions/vote"
}
}
],
"responses":{
"200":{
"description":"vote response",
"schema":{
"$ref":"#/definitions/vote"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/expert":{
"get":{
"description":"Returns all experts from the system that the user has access to",
"operationId":"findExperts",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"categories",
"in":"query",
"description":"categories to filter by",
"required":false,
"type":"array",
"items":{
"type":"string"
},
"collectionFormat":"csv"
},
{
"name":"limit",
"in":"query",
"description":"maximum number of results to return",
"required":false,
"type":"integer",
"format":"int32"
}
],
"responses":{
"200":{
"description":"expert response",
"schema":{
"type":"array",
"items":{
"$ref":"#/definitions/expert"
}
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"post":{
"description":"Creates a new expert in the system.",
"operationId":"addExpert",
"produces":[
"application/json"
],
"parameters":[
{
"name":"expert",
"in":"body",
"description":"expert to add to the system",
"required":true,
"schema":{
"$ref":"#/definitions/expert"
}
}
],
"responses":{
"200":{
"description":"expert response",
"schema":{
"$ref":"#/definitions/expert"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/expert/{id}":{
"get":{
"description":"Returns an expert based on a single ID",
"operationId":"findExpertById",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of expert to fetch",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"200":{
"description":"expert response",
"schema":{
"$ref":"#/definitions/expert"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"delete":{
"description":"deletes a single expert based on the ID supplied",
"operationId":"deleteExpert",
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of expert to delete",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"204":{
"description":"expert deleted"
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
},
"/expert/{id}/trust":{
"get":{
"description":"Returns trust representations based on a single ID",
"operationId":"findRepresentationsById",
"produces":[
"application/json",
"application/xml",
"text/xml",
"text/html"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of expert trust representations to fetch",
"required":true,
"type":"integer",
"format":"int64"
}
],
"responses":{
"200":{
"description":"representation response",
"schema":{
"type":"array",
"items":{
"$ref":"#/definitions/representation"
}
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
},
"post":{
"description":"Creates a new representation in the system.",
"operationId":"addRepresentation",
"produces":[
"application/json"
],
"parameters":[
{
"name":"id",
"in":"path",
"description":"ID of expert to trust",
"required":true,
"type":"integer",
"format":"int64"
},
{
"name":"representation",
"in":"body",
"description":"Representation to add to the system",
"required":true,
"schema":{
"$ref":"#/definitions/representation"
}
}
],
"responses":{
"200":{
"description":"representation response",
"schema":{
"$ref":"#/definitions/representation"
}
},
"default":{
"description":"unexpected error",
"schema":{
"$ref":"#/definitions/errorModel"
}
}
}
}
}
},
"definitions":{
"user":{
"required":[
"id",
"name",
"email"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"name":{
"type":"string"
},
"email":{
"type":"string"
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"category":{
"required":[
"id",
"name",
"description"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"name":{
"type":"string"
},
"description":{
"type":"string"
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"option":{
"required":[
"id",
"name",
"description"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"name":{
"type":"string"
},
"description":{
"type":"string"
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"proposition":{
"required":[
"id",
"name",
"description"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"name":{
"type":"string"
},
"tag":{
"type":"string"
},
"description":{
"type":"string"
},
"options":{
"type":"array",
"items":{
"$ref":"#/definitions/option"
}
},
"categories":{
"type":"array",
"items":{
"$ref":"#/definitions/category"
}
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"vote":{
"required":[
"id",
"user",
"proposition",
"option",
"vote"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"user":{
"$ref":"#/definitions/user"
},
"proposition":{
"$ref":"#/definitions/proposition"
},
"option":{
"$ref":"#/definitions/option"
},
"vote":{
"type":"integer",
"format":"int32"
},
"timestamp":{
"type":"string",
"format":"date-time"
},
"comment":{
"type":"string"
}
}
},
"expert":{
"required":[
"id",
"user",
"category",
"expertise"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"user":{
"$ref":"#/definitions/user"
},
"category":{
"$ref":"#/definitions/category"
},
"expertise":{
"type":"string"
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"representation":{
"required":[
"id",
"user",
"expert",
"trust"
],
"properties":{
"id":{
"type":"integer",
"format":"int64"
},
"user":{
"$ref":"#/definitions/user"
},
"expert":{
"$ref":"#/definitions/user"
},
"trust":{
"type":"integer",
"format":"int32"
},
"timestamp":{
"type":"string",
"format":"date-time"
}
}
},
"errorModel":{
"required":[
"code",
"message"
],
"properties":{
"code":{
"type":"integer",
"format":"int32"
},
"message":{
"type":"string"
}
}
}
}
}