Elimina le ridondanze in RAML con tipi di risorse e tratti

Questo articolo fa parte di una serie: • Introduzione a RAML - Il linguaggio di modellazione API RESTful

• Elimina le ridondanze in RAML con tipi di risorse e tratti (articolo corrente) • RAML modulare che utilizza include, librerie, sovrapposizioni ed estensioni

• Definire le proprietà RAML personalizzate utilizzando le annotazioni

1. Panoramica

Nel nostro articolo tutorial RAML, abbiamo introdotto il linguaggio di modellazione API RESTful e creato una semplice definizione API basata su una singola entità chiamata Foo . Ora immagina un'API del mondo reale in cui hai diverse risorse di tipo entità, tutte con operazioni GET, POST, PUT e DELETE uguali o simili. Puoi vedere come la tua documentazione API può diventare rapidamente noiosa e ripetitiva.

In questo articolo, mostriamo come l'uso dei tipi di risorse e delle funzionalità dei tratti in RAML può eliminare le ridondanze nelle definizioni di risorse e metodi estraendo e parametrizzando le sezioni comuni, eliminando così gli errori di copia e incolla e rendendo le definizioni API più concise.

2. La nostra API

Per dimostrare i vantaggi dei tipi e delle caratteristiche delle risorse , espanderemo la nostra API originale aggiungendo risorse per un secondo tipo di entità chiamato Bar . Ecco le risorse che costituiranno la nostra API rivista:

  • OTTIENI / api / v1 / foos
  • POST / api / v1 / foos
  • OTTIENI / api / v1 / foos / {fooId}
  • PUT / api / v1 / foos / {fooId}
  • DELETE / api / v1 / foos / {fooId}
  • OTTIENI / api / v1 / foos / name / {name}
  • OTTIENI / api / v1 / foos? Name = {name} & ownerName = {ownerName}
  • OTTIENI / api / v1 / bar
  • POST / api / v1 / bar
  • OTTIENI / api / v1 / bars / {barId}
  • PUT / api / v1 / bars / {barId}
  • ELIMINA / api / v1 / bars / {barId}
  • OTTIENI / api / v1 / bars / fooId / {fooId}

3. Riconoscere i modelli

Mentre leggiamo l'elenco delle risorse nella nostra API, iniziamo a vedere emergere alcuni modelli. Ad esempio, esiste un modello per gli URI e i metodi utilizzati per creare, leggere, aggiornare ed eliminare singole entità e c'è un modello per gli URI e i metodi utilizzati per recuperare le raccolte di entità. Il pattern collection e collection-item è uno dei pattern più comuni usati per estrarre i tipi di risorse nelle definizioni RAML.

Diamo un'occhiata a un paio di sezioni della nostra API:

[Nota: negli snippet di codice seguenti, una riga contenente solo tre punti (...) indica che alcune righe vengono ignorate per brevità.]

/foos: get: description: | List all foos matching query criteria, if provided; otherwise list all foos queryParameters: name?: string ownerName?: string responses: 200: body: application/json: type: Foo[] post: description: Create a new foo body: application/json: type: Foo responses: 201: body: application/json: type: Foo ... /bars: get: description: | List all bars matching query criteria, if provided; otherwise list all bars queryParameters: name?: string ownerName?: string responses: 200: body: application/json: type: Bar[] post: description: Create a new bar body: application/json: type: Bar responses: 201: body: application/json: type: Bar

Quando confrontiamo le definizioni RAML delle risorse / foos e / bars , inclusi i metodi HTTP utilizzati, possiamo vedere diverse ridondanze tra le varie proprietà di ciascuna, e di nuovo vediamo emergere dei pattern.

Ovunque sia presente uno schema nella definizione di una risorsa o di un metodo, è possibile utilizzare un tipo o un tratto di risorsa RAML .

4. Tipi di risorse

Per implementare i modelli trovati nell'API, i tipi di risorsa utilizzano parametri riservati e definiti dall'utente circondati da doppie parentesi angolari (<>).

4.1 Parametri riservati

È possibile utilizzare due parametri riservati nelle definizioni del tipo di risorsa:

  • <> rappresenta l'intero URI (che segue baseURI ) e
  • <> rappresenta la parte dell'URI che segue la barra più a destra (/), ignorando le parentesi graffe {}.

Quando vengono elaborati all'interno di una definizione di risorsa, i loro valori vengono calcolati in base alla risorsa da definire.

Data la risorsa / foos , ad esempio, <> restituirà "/ foos" e <> restituirà "foos".

Data la risorsa / foos / {fooId} , <> restituirà "/ foos / {fooId}" e <> restituirà "foos ".

4.2 Parametri definiti dall'utente

A resource type definition may also contain user-defined parameters. Unlike the reserved parameters, whose values are determined dynamically based on the resource being defined, user-defined parameters must be assigned values wherever the resource type containing them is used, and those values do not change.

User-defined parameters may be declared at the beginning of a resource type definition, although doing so is not required and is not common practice, as the reader can usually figure out their intended usage given their names and the contexts in which they are used.

4.3 Parameter Functions

A handful of useful text functions are available for use wherever a parameter is used in order to transform the expanded value of the parameter when it is processed in a resource definition.

Here are the functions available for parameter transformation:

  • !singularize
  • !pluralize
  • !uppercase
  • !lowercase
  • !uppercamelcase
  • !lowercamelcase
  • !upperunderscorecase
  • !lowerunderscorecase
  • !upperhyphencase
  • !lowerhyphencase

Functions are applied to a parameter using the following construct:

<<parameterName | !functionName>>

If you need to use more than one function to achieve the desired transformation, you would separate each function name with the pipe symbol (“|”) and prepend an exclamation point (!) before each function used.

For example, given the resource /foos, where <<resourcePathName>> evaluates to “foos”:

  • <<resourcePathName | !singularize>> ==> “foo”
  • <<resourcePathName | !uppercase>> ==> “FOOS”
  • <<resourcePathName | !singularize | !uppercase>> ==> “FOO”

And given the resource /bars/{barId}, where <<resourcePathName>> evaluates to “bars”:

  • <<resourcePathName | !uppercase>> ==> “BARS”
  • <<resourcePathName | !uppercamelcase>> ==> “Bar”

5. Extracting a Resource Type for Collections

Let's refactor the /foos and /bars resource definitions shown above, using a resource type to capture the common properties. We will use the reserved parameter <>, and the user-defined parameter <> to represent the data type used.

5.1 Definition

Here is a resource type definition representing a collection of items:

resourceTypes: collection: usage: Use this resourceType to represent any collection of items description: A collection of <> get: description: Get all <>, optionally filtered responses: 200: body: application/json: type: <>[] post: description: Create a new <> responses: 201: body: application/json: type: <>

Note that in our API, because our data types are merely capitalized, singular versions of our base resources' names, we could have applied functions to the <<resourcePathName>> parameter, instead of introducing the user-defined <<typeName>> parameter, to achieve the same result for this portion of the API:

resourceTypes: collection: ... get: ... type: <>[] post: ... type: <>

5.2 Application

Using the above definition that incorporates the <<typeName>> parameter, here is how you would apply the “collection” resource type to the resources /foos and /bars:

/foos: type: { collection: { "typeName": "Foo" } } get: queryParameters: name?: string ownerName?: string ... /bars: type: { collection: { "typeName": "Bar" } }

Notice that we are still able to incorporate the differences between the two resources — in this case, the queryParameters section — while still taking advantage of all that the resource type definition has to offer.

6. Extracting a Resource Type for Single Items of a Collection

Let's focus now on the portion of our API dealing with single items of a collection: the /foos/{fooId} and /bars/{barId} resources. Here is the code for/foos/{fooId}:

/foos: ... /{fooId}: get: description: Get a Foo responses: 200: body: application/json: type: Foo 404: body: application/json: type: Error example: !include examples/Error.json put: description: Update a Foo body: application/json: type: Foo responses: 200: body: application/json: type: Foo 404: body: application/json: type: Error example: !include examples/Error.json delete: description: Delete a Foo responses: 204: 404: body: application/json: type: Error example: !include examples/Error.json

The /bars/{barId} resource definition also has GET, PUT, and DELETE methods and is identical to the /foos/{fooId} definition, other than the occurrences of the strings “foo” and “bar” (and their respective pluralized and/or capitalized forms).

6.1 Definition

Extracting the pattern we just identified, here is how we define a resource type for single items of a collection:

resourceTypes: ... item: usage: Use this resourceType to represent any single item description: A single <> get: description: Get a <> responses: 200: body: application/json: type: <> 404: body: application/json: type: Error example: !include examples/Error.json put: description: Update a <> body: application/json: type: <> responses: 200: body: application/json: type: <> 404: body: application/json: type: Error example: !include examples/Error.json delete: description: Delete a <> responses: 204: 404: body: application/json: type: Error example: !include examples/Error.json

6.2 Application

And here is how we apply the “item” resource type:

/foos: ... /{fooId}: type: { item: { "typeName": "Foo" } }
... /bars: ... /{barId}: type: { item: { "typeName": "Bar" } }

7. Traits

Whereas a resource type is used to extract patterns from resource definitions, a trait is used to extract patterns from method definitions that are common across resources.

7.1 Parameters

Along with <<resourcePath>> and <<resourcePathName>>, one additional reserved parameter is available for use in trait definitions: <<methodName>> evaluates to the HTTP method (GET, POST, PUT, DELETE, etc) for which the trait is defined. User-defined parameters may also appear within a trait definition, and where applied, take on the value of the resource in which they are being applied.

7.2 Definition

Notice that the “item” resource type is still full of redundancies. Let's see how traits can help eliminate them. We'll start by extracting a trait for any method containing a request body:

traits: hasRequestItem: body: application/json: type: <>

Now let's extract traits for methods whose normal responses contain bodies:

 hasResponseItem: responses: 200: body: application/json: type: <> hasResponseCollection: responses: 200: body: application/json: type: <>[]

Finally, here's a trait for any method that could return a 404 error response:

 hasNotFound: responses: 404: body: application/json: type: Error example: !include examples/Error.json

7.3 Application

We then apply this trait to our resource types:

resourceTypes: collection: usage: Use this resourceType to represent any collection of items description: A collection of <> get: description: | Get all <>, optionally filtered is: [ hasResponseCollection: { typeName: <> } ] post: description: Create a new <> is: [ hasRequestItem: { typeName: <> } ] item: usage: Use this resourceType to represent any single item description: A single <> get: description: Get a <> is: [ hasResponseItem: { typeName: <> }, hasNotFound ] put: description: Update a <> is: | [ hasRequestItem: { typeName: <> }, hasResponseItem: { typeName: <> }, hasNotFound ] delete: description: Delete a <> is: [ hasNotFound ] responses: 204:

We can also apply traits to methods defined within resources. This is especially useful for “one-off” scenarios where a resource-method combination matches one or more traits but does not match any defined resource type:

/foos: ... /name/{name}: get: description: List all foos with a certain name is: [ hasResponseCollection: { typeName: Foo } ]

8. Conclusion

In this tutorial, we've shown how to significantly reduce or, in some cases, eliminate redundancies from a RAML API definition.

First, we identified the redundant sections of our resources, recognized their patterns, and extracted resource types. Then we did the same for the methods that were common across resources to extract traits. Then we were able to eliminate further redundancies by applying traits to our resource types and to “one-off” resource-method combinations that did not strictly match one of our defined resource types.

As a result, our simple API with resources for only two entities, was reduced from 177 to just over 100 lines of code. To learn more about RAML resource types and traits, visit the RAML.org 1.0 spec.

L' implementazione completa di questo tutorial può essere trovata nel progetto github.

Ecco la nostra API RAML finale nella sua interezza:

#%RAML 1.0 title: Baeldung Foo REST Services API version: v1 protocols: [ HTTPS ] baseUri: //rest-api.baeldung.com/api/{version} mediaType: application/json securedBy: basicAuth securitySchemes: basicAuth: description: | Each request must contain the headers necessary for basic authentication type: Basic Authentication describedBy: headers: Authorization: description: | Used to send the Base64 encoded "username:password" credentials type: string responses: 401: description: | Unauthorized. Either the provided username and password combination is invalid, or the user is not allowed to access the content provided by the requested URL. types: Foo: !include types/Foo.raml Bar: !include types/Bar.raml Error: !include types/Error.raml resourceTypes: collection: usage: Use this resourceType to represent a collection of items description: A collection of <> get: description: | Get all <>, optionally filtered is: [ hasResponseCollection: { typeName: <> } ] post: description: | Create a new <> is: [ hasRequestItem: { typeName: <> } ] item: usage: Use this resourceType to represent any single item description: A single <> get: description: Get a <> is: [ hasResponseItem: { typeName: <> }, hasNotFound ] put: description: Update a <> is: [ hasRequestItem: { typeName: <> }, hasResponseItem: { typeName: <> }, hasNotFound ] delete: description: Delete a <> is: [ hasNotFound ] responses: 204: traits: hasRequestItem: body: application/json: type: <> hasResponseItem: responses: 200: body: application/json: type: <> hasResponseCollection: responses: 200: body: application/json: type: <>[] hasNotFound: responses: 404: body: application/json: type: Error example: !include examples/Error.json /foos: type: { collection: { typeName: Foo } } get: queryParameters: name?: string ownerName?: string /{fooId}: type: { item: { typeName: Foo } } /name/{name}: get: description: List all foos with a certain name is: [ hasResponseCollection: { typeName: Foo } ] /bars: type: { collection: { typeName: Bar } } /{barId}: type: { item: { typeName: Bar } } /fooId/{fooId}: get: description: Get all bars for the matching fooId is: [ hasResponseCollection: { typeName: Bar } ]
Avanti » RAML modulare che utilizza include, librerie, sovrapposizioni ed estensioni « Precedente Introduzione a RAML - Il linguaggio di modellazione API RESTful