API Ponzu: come invocarle e come configurarle

API Ponzu, introduzione

Nell’articolo precedente abbiamo visto come installare il CMS Headless PONZU su una macchina FreeBSD, adesso vedremo come invocarne le API e soprattutto come configurarle.

API in GET

Le API per richiamare i contenuti inseriti in PONZU vanno invocate col verbo GET e permettono di ricercare tramite id o slug:

Ricerca per id: http://www.miocsms.it:8080/api/content?type=Agenzia&id=1

 curl -X GET \
'http://www.miocsms.it:8080/api/content?type=Agenzia&id=1' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Host: www.miocsms.it:8080' \
-H 'Postman-Token: 15a04745-a727-4655-be6e-fa59736af513,a0c9aac8-e144-465f-9383-f8011bc1ec1a' \
-H 'User-Agent: PostmanRuntime/7.19.0' \
-H 'cache-control: no-cache' 

Ed otterremo una risposta simile alla seguente:

{    "data": [
        {            
           "uuid": "e7a983f8-0d26-49d8-9ecca5bcf489c23",
            "id": 1,            
            "slug": "agenzia-e7a983f8-0d26-49d8-9ecc-7a5bcf489c23",            
            "timestamp": 1570315593000,
            "updated": 1570286313899,
            "nome": "Pippo",
            "zona": "Italia",
            "description": "test",
            "image": ""        }
    ]
}

Se invece vogliamo l’elenco di tutti i contenuti di tipo Venditore dovremo invocare la seguente API:

  http://www.miocms.it:8080/api/contents?type=Venditore 
 {
    "data": [
        {
            "uuid": "8b28886a-79ab-46da-ab81-04f13666887d",
            "id": 5,
            "slug": "venditore-bino-bini",
            "timestamp": 1570434435420,
            "updated": 1570434435420,
            "nome": "Bino",
            "cognome": "Binis",
            "telefono": 12345,
            "agenzia": "/api/content?type=Agenzia&id=1"
        },
        {
            "uuid": "08763c92-4421-4547-9cb4-946309b4ac9b",
            "id": 4,
            "slug": "venditore-emilio-emili",
            "timestamp": 1570423614000,
            "updated": 1570423614977,
            "nome": "Emilio",
            "cognome": "Emili",
            "telefono": 5,
            "agenzia": ""
        },
        {
            "uuid": "09fe8f29-d20f-43d1-9815-d4666453948b",
            "id": 3,
            "slug": "venditore-emilio-butraguegno",
            "timestamp": 1570423515000,
            "updated": 1570423575562,
            "nome": "Emilio",
            "cognome": "Butraguegno",
            "telefono": 3356565,
            "agenzia": "/api/content?type=Agenzia&id=2"
        },
        {
            "uuid": "006d41bf-f64e-4568-8381-4d30adb2254a",
            "id": 2,
            "slug": "venditoresilviodellagiovanna",
            "timestamp": 1570423490000,
            "updated": 1570423490674,
            "nome": "Silvio",
            "cognome": "Della Giovanna",
            "telefono": 3356565,
            "agenzia": "/api/content?type=Agenzia&id=2"
        }
    ]
} 

Infine non ci resta che vedere come invocare un’api di ricerca, in questo caso come cercare un venditore per nome e cognome:

La sintassi sarà simile alla seguente, http://www.miocms.it:8080/api/search?type=Venditore&q=+cognome:Butraguegno&+nome:Emilio

curl -X GET \
   'http://www.miocms.it:8080/api/search?type=Venditore&q=+cognome:Butraguegno&nome:Emilio=&+nome:Emilio=' \
   -H 'Accept: /' \
   -H 'Accept-Encoding: gzip, deflate' \
   -H 'Cache-Control: no-cache' \
   -H 'Connection: keep-alive' \
   -H 'Host: miocms.it:8080' \
   -H 'Postman-Token: 4458e213-b324-4eb9-8262-8bf12b5db7c2,d59a281b-bcb4-4792-aa13-f1d900196cd0' \
   -H 'User-Agent: PostmanRuntime/7.19.0' \
   -H 'cache-control: no-cache'

La risposta sarà simile a quella vista nella chiamata precedente.

Per maggiori informazioni su come creare le query: http://blevesearch.com/docs/Query-String-Query/

Configurare le API Ponzu per inserimento e modifica

Prima di poter invocare le nostre api di inserimento o modifica contenuti dovremo abilitare i vari contenuti creati, nel nostro caso “Agenzie” e “Venditori”.

Innanzitutto dobbiamo aprire con un editor i file agenzie.go e venditori.go generati in precedenza ed aggiungere nelle importazioni “”net/http””:

import (
     "fmt"
     "net/http"  
     "github.com/ponzu-cms/ponzu/management/editor" 
     "github.com/ponzu-cms/ponzu/system/item"
 )

ed aggiungere in fondo al listato queste funzioni:

func (v *Venditore) Create(res http.ResponseWriter, req *http.Request) error {
     return nil
 }
 func (v *Venditore) Update(res http.ResponseWriter, req *http.Request) error {
     //addr := req.RemoteAddr
         return nil
 }
 func (v *Venditore) AutoApprove(res http.ResponseWriter, req *http.Request) error {
         return nil
 }

Dove al posto di v *Venditore andrà inserito il valore già presente nella funzione “IndexContent()” .

In questo modo abbiamo abilitato le api di inserimento e modifica ed abbiamo configurato la auto-approvazione dei contenuti inviati tramite API in modo da renderli subito disponibili.

Ecco un esempio di file completo:

package content
 import (
     "fmt"
"net/http" "github.com/bosssauce/reference" "github.com/ponzu-cms/ponzu/management/editor" "github.com/ponzu-cms/ponzu/system/item"
 )
 type Venditore struct {
     item.Item
Nome     string `json:"nome"` Cognome  string `json:"cognome"` Telefono int    `json:"telefono"` Agenzia  string `json:"agenzia"`
 }
 // MarshalEditor writes a buffer of html to edit a Venditore within the CMS
 // and implements editor.Editable
 func (v *Venditore) MarshalEditor() ([]byte, error) {
     view, err := editor.Form(v,
         // Take note that the first argument to these Input-like functions
         // is the string version of each Venditore field, and must follow
         // this pattern for auto-decoding and auto-encoding reasons:
         editor.Field{
             View: editor.Input("Nome", v, map[string]string{
                 "label":       "Nome",
                 "type":        "text",
                 "placeholder": "Enter the Nome here",
             }),
         },
         editor.Field{
             View: editor.Input("Cognome", v, map[string]string{
                 "label":       "Cognome",
                 "type":        "text",
                 "placeholder": "Enter the Cognome here",
             }),
         },
         editor.Field{
             View: editor.Input("Telefono", v, map[string]string{
                 "label":       "Telefono",
                 "type":        "text",
                 "placeholder": "Enter the Telefono here",
             }),
         },
         editor.Field{
             View: reference.Select("Agenzia", v, map[string]string{
                 "label": "Agenzia",
             },
                 "Agenzia",
                 {{ .nome }},
             ),
         },
     )
if err != nil {     return nil, fmt.Errorf("Failed to render Venditore editor view: %s", err.Error()) } return view, nil
 }
 func init() {
     item.Types["Venditore"] = func() interface{} { return new(Venditore) }
 }
 // String defines how a Venditore is printed. Update it using more descriptive
 // fields from the Venditore struct type
 func (v *Venditore) String() string {
     return fmt.Sprintf("Venditore: %s %s", v.Nome, v.Cognome)       
 }
 func (v *Venditore) Push() []string {
     return []string{
         "Nome",
         "Cognome",
     }
 }
 func (v *Venditore)  IndexContent() bool {
     return true
 }
 func (v *Venditore) Create(res http.ResponseWriter, req *http.Request) error {
     return nil
 }
 func (v *Venditore) Update(res http.ResponseWriter, req *http.Request) error {
     //addr := req.RemoteAddr
         return nil
 }
 func (v *Venditore) AutoApprove(res http.ResponseWriter, req *http.Request) error {
         return nil
 }

Inserimento e modifica, invochiamo le api

Concludendo, andiamo ad invocare le API di inserimento e modifica dati, abilitate poco sopra. Vediamo l’inserimento di un nuovo venditore:

L’API va ovviamente chiamata in POST, utilizzando il context” /api/content/create?type=” e quindi indicando la tipologia di contenuto da creare:

 POST http:miocms:8080/api/content/create?type=Venditore 

Il content type deve essere di tipo ” multipart/form-data ” ed il body contenere le coppie chiave/valore necessarie per creare la risorsa, ecco un esempio:

curl -X POST \
   'http://miocms:8080/api/content/create?type=Venditore' \
   -H 'Content-Type: multipart/form-data' \
   -H 'Postman-Token: 497d323c-9678-4f52-b0a5-7a2407eb7994' \
   -H 'cache-control: no-cache' \
   -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
   -F nome=Tizio \
   -F cognome=Caio \
   -F codice=TC001 \
   -F stato=attivo \
   -F telefono=0574532585 \
   -F 'agenzia=/api/content?type=Agenzia&id=1' \
   -F 'settore=/api/content?type=SettoreVenditore&id=4'

Tutti quei valori che fanno riferimento ad altre tabelle/tipo dato, ad esempio l’agenzia di riferimento del nostro venditore, dovrà essere inviata con una sintassi simile alla seguente: /api/content?type=Agenzia&id= specificando l’id della risorsa collegata.

Per quanto riguarda invece l’API di modifica, questa verrà invocata in modo molto simile a quella di inserimento, cambia solo il contesto:

 /api/content/update?type=Venditore&id=2 

infatti abbiamo “update” come azione da compiere ed inoltre va specificato come parametro di query l’id del contenuto da modificare

Riferimenti

https://docs.ponzu-cms.org/HTTP-APIs/Content/

http://blevesearch.com/docs/Query-String-Query/

https://snipcart.com/blog/golang-ecommerce-ponzu-cms-demo

https://github.com/ponzu-cms/ponzu/tree/master/examples

0 comments on “API Ponzu: come invocarle e come configurarleAdd yours →

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *