RAML V0.8

MODELADO DE API CON

TEXT

CONTRATO

AGENDA

▸ Definición

▸ Traits

▸ ResourceTypes

▸ Schemas

▸ Examples

▸ Methods: get, post, delete, put

▸ Tools

PARAMETROS GENERALES

#%RAML 0.8

title: Aptitus

baseUri: https://api.aptitus.com/

version: v2

mediaType: application/json

GET WITH QUERY PARAMETERS

/institutions:

get:

queryParameters:

q:

description: Text to autocomplete

example: Avancys

responses:

200:

body:

schema: baseInstitutionsGetResponse

example: !include ./examples/base/base.institutions.get.response.json

TRAITS - PAGED.RML

queryParameters:

page_size:

description: The number of items per page

type: number

default: 20

page:

description: The page to return

type: number

default: 0

example: 3

TRAITS - API.RML

traits:

- paged: !include traits/paged.raml

/institutions:

is: [paged]

displayName: Institutions

get:

description: Get the institutions that match your search.

RESOURCETYPES - BASE.RAML

get?:

responses:

200:

description: Returned if the the request invalid.

400?:

description: Returned if the the request is invalid.

404?:

description: Returned if the object is not found.

500?:

description: Returned if an error occurs while retrieving.

RESOURCETYPES - API.RAML

/institutions:

type: base

displayName: Institutions

get:

description: |

Get the institutions that match your search.

This service doesn't need that user is logged in.

SCHEMAS

{

"$schema": "http://json-schema.org/draft-04/schema#",

"type": "object",

"properties": {

"code": {

"type": "integer"

},

"message": {

"type": "string"

}

},

"required": ["code", "message"]

}

SCHEMAS

version: v2

mediaType: application/json

schemas:

- error: !include schemas/error.json

EXAMPLES

examples/institutions.get.400.json:

{

"code": 400,

"message": "Debe ingresar una institución"

}

EXAMPLES

/institutions:

displayName: Institutions

get:

400:

body:

application/json:

schema: error

example: !include ./examples/institutions.get.400.json

MÉTODOS GET WITH QUERY PARAMETERS

/institutions:

get:

queryParameters:

q:

description: Text to autocomplete

example: Avancys

responses:

200:

body:

schema: baseInstitutionsGetResponse

example: !include ./examples/base/base.institutions.get.response.json

MÉTODOS GET WITH HEADERS

/synchronize:

get:

headers:

Authorization:

example: Bearer 3b4547126957a718f94540b676fbd0ebc282b5ea

responses:

200:

body:

schema: synchronizeGetResponse

example: !include ./examples/synchronize.get.response.json

MÉTODO POST

/oauth2:

/authorize:

post:

body:

schema: oauth2AuthorizePostRequest

example: !include ./examples/identity/oauth2_authorize.post.request.json

responses:

201:

body:

application/json:

schema: oauth2AuthorizePostResponse

example: !include ./examples/identity/oauth2_authorize.post.response.json

MÉTODO PUT

/experiences:

/{id}:

put:

body:

schema: postulantExperiencePutRequest

example: !include ./examples/experiences/postulant.experience.put.request.json

responses:

200:

body:

schema: postulantExperiencePutResponse

example: !include ./examples/experiences/postulant.experience.put.response.json

MÉTODO DELETE

/experiences:

/{id}:

delete:

description: |

Delete an experience from Postulant. For this service is necessary that the

postulant is logged in.

responses:

200:

body:

schema: postulantExperienceDeleteResponse

example: !include ./examples/experiences/postulant.experience.delete.response.json

EXTRA

▸ Documentacion http://raml.org/

▸ Fake api: raml-mockup

▸ Api design: Atom + Api-workbench

▸ Example to Schema http://jsonschema.net/#/

▸ Generate html https://github.com/raml2html/raml2html

▸ Testing https://github.com/cybertk/abao $ abao api.raml --server http://localhost:8080

RAML-MOCKUP

▸ raml-mockup api.raml -d schemas -f http://json-schema.org -p 5000 -w

▸ Browser: http://localhost:5000/salaries

▸ CLI: $ http POST http://localhost:5000/oauth2/authorize

RAML2HTML

▸ raml2html api.raml > ./html/index.html

▸ Open index.html on browser

▸ CLI: $ http http://localhost:8001/#institutions_get