๐ Definition A machine readable definition of an API interface, using a common format like API Blueprint, Swagger or RAML, providing a definition of the surface area of the resources that are available via API. API definitions are proving to be very useful in establishing a common way to describe, communicate and collaborate around APIs, which are often extremely abstract. ...from apievangelist.com
Example : XDR as an API Contract
const ADD = 601;
const SUBTRACT = 602;
... // omitted for brevity
struct AddWork {
int num1;
int num2;
int num3;
int num4;
};
struct AddResult {
int num;
int err;
};
...// omitted for brevity
union calc_req switch ( int op ) {
case ADD : AddWork add_request;
case SUBTRACT : SubWork sub_request;
... // omitted for brevity
};
union calc_res switch ( int op ) {
case ADD : AddResult add_result;
case SUBTRACT : SubResult sub_result;
... // omitted for brevity
};
Service Request : ZMQ as Transport Layer
void test_add(void)
{
AddWork Req;
AddResult Res;
Req.num1 = 3;
Req.num2 = 13;
Req.num3 = 25;
Req.num4 = 77;
char msgbuf[msgsize];
encode( msgbuf, msgsize, ADD, &Req);
transport( msgbuf, msgsize); // ZMQ
decode( msgbuf, msgsize, &Res );
assert( 0 == Res.err );
assert( Req.num1 + Req.num2 + Req.num3 + Req.num4 == Res.num);
}
void encode( char *msgbuf, int msgsize, int op, T *Req ){
XDR xdr;
calc_req req = {0};
req.op = op;
switch(req.op) {
case ADD :
memcpy(&req.calc_req_u.add_request, Req, sizeof(T));
break;
case SUBTRACT :
...
}
xdrmem_create (&xdr, msgbuf, msgsize , XDR_ENCODE);
if (!xdr_calc_req (&xdr, &req)) {
fprintf (stderr, "req: could not encode\n");
exit (1);
}
xdr_free((xdrproc_t) xdr_calc_req, (char *) &req);
xdr_destroy(&xdr);
return;
}
void decode( char *msgbuf, int msgsize, T *Res ){
XDR xdr;
calc_res res = {0};
xdrmem_create ( &xdr, msgbuf, msgsize, XDR_DECODE);
if (!xdr_calc_res (&xdr, &res)) {
fprintf (stderr, "res: could not decode\n");
exit (1);
}
switch(res.op) {
case ADD :
memcpy(Res, &res.calc_res_u.add_result, sizeof(T));
break;
case SUBTRACT:
...
}
xdr_free((xdrproc_t) xdr_calc_res, (char *) &res);
xdr_destroy(&xdr);
}
- Swagger to define RESTful APIs
- gRPC
- Apache Thrift
- facebook Thrift , aka FBThrift (i.e, FBOSS Agent )
- Apache Avro
- Gravizo Guide