View
36
Download
3
Category
Preview:
Citation preview
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
Recommended