Google风格API响应

Question

在错误地设计了第一个API响应之后，我决定使用下面的Google风格指南。

下面是我用PHP创建的场景，我有一个关于场景3的问题。

<?php 


# JSON GET - RESPONSE SCENARIOS


# SCENARIO 1 - GET
# MULTIPLE RECORDS
$var_Success_Records = 
(object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/estimates/',
    'data' => (object)[
    'totalItems' => (int)6741,
    'startIndex' => (int)1,
    'itemsPerPage' => (int)1,
    'records' => [

        (object)[
            'id' => (string)'1001',
            'created' => (string)'2020-01-01 00:00:01',
            'modified' => (string)'2020-01-02 00:00:01',
            'status' => (string)'draft',
            'type' => (string)'Commercial',
        ],
        (object)[
            'id' => (string)'1002',
            'created' => (string)'2020-01-10 00:00:01',
            'modified' => (string)'2020-01-12 00:00:01',
            'status' => (string)'draft',
            'type' => (string)'Residential',
        ],

    ]
    ]
];


# SCENARIO 2 - GET
# SINGLE RECORD
$var_Success_Record = 
(object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/estimates/1001',

    'data' => (object)[
    'id' => (string)'1001',
    'created' => (string)'2020-01-01 00:00:01',
    'modified' => (string)'2020-01-02 00:00:01',
    'status' => (string)'draft',
    'type' => (string)'Commercial',
    ],

];


# SCENARIO 3 - GET
# NO RECORD FOUND
$var_Success_NoRecord = 
(object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/estimates/1003',
    'error' => (object)[
    'code' => (string)'ERR-001',
    'message' => (string)'No record found.'
    ],
];


# SCENARIO 4 - GET
# DATABASE ERROR
$var_Error_Database = 
(object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/estimates/',
    'error' => (object)[
    'code' => (string)'ERR-002',
    'message' => (string)'Database error.'
    ],
];


# JSON POST - RESPONSE SCENARIOS


# SCENARIO 5 - POST
# SINGLE RECORD INSERT SUCCESS
$var_Success_Post = 
(object)[
    'success' => (object)[
    'data' => null,
    'message' => 'Estimate created.'
    ]
];


# SCENARIO 6 - POST
# SINGLE RECORD INSERT ERROR
$var_Error_Post = 
(object)[
    'error' => (object)[
    'code' => null,
    'message' => 'Estimate not created.'
    ]
];


# Set JSON Header...
header('Content-type:application/json;charset=utf-8');

print_r(json_encode($var_Success_Records));


?>

当用户选择记录但没有找到记录时，这是错误还是成功？

Answer 1

好的。我相信我明白劳伦斯和Wahyu在上面的评论中提到了什么。

下面是修改后的场景

<?php 


# JSON GET/POST/PUT/DELETE - RESPONSE SCENARIOS


######################################################################
######################################################################
######################################################################


# SCENARIO 1.0 - GET
# SELECT RECORDS SQL - SELECT * FROM table WHERE status = 'active'
$getRecordsResponse_Success = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/records/',
  'status' => (string)'OK',
  'data' => (object)[
    'totalItems' => (int)6741,
    'startIndex' => (int)1,
    'itemsPerPage' => (int)1,
    'records' => [

      (object)[
      'id' => (string)'1001',
      'created' => (string)'2020-01-01 00:00:01',
      'modified' => (string)'2020-01-02 00:00:01',
      'status' => (string)'draft',
      'type' => (string)'Commercial',
      ],

      (object)[
      'id' => (string)'1002',
      'created' => (string)'2020-01-10 00:00:01',
      'modified' => (string)'2020-01-12 00:00:01',
      'status' => (string)'draft',
      'type' => (string)'Residential',
      ],

    ]
  ]
];


# SCENARIO 1.1 - GET
# SELECT RECORDS SQL - NO RECORDS FOUND
$getRecordsResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/records/',
  'error' => (object)[
    'code' => (string)'ERR-000',
    'message' => 'Records not found.'
    ]
  ];


######################################################################
######################################################################
######################################################################


# SCENARIO 2.0 - GET
# SELECT RECORD SQL - SELECT id, status WHERE id = 1001
$getRecordResponse_Success = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/records/1001',
  'status' => (string)'OK',

  'data' => (object)[
    'id' => (string)'1001',
    'created' => (string)'2020-01-01 00:00:01',
    'modified' => (string)'2020-01-02 00:00:01',
    'status' => (string)'draft',
    'type' => (string)'Commercial',
  ],

];


# SCENARIO 2.1 - GET
# SELECT RECORD SQL - NO RECORD FOUND
$getRecordResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/records/1001',
  'error' => (object)[
    'code' => (string)'ERR-000',
    'message' => 'Record not found.'
  ]
];


######################################################################
######################################################################
######################################################################


# SCENARIO 3.0 - POST
# INSERT RECORD SQL - INSERT record INTO table
$postRecordResponse_Success = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'post/record/',
  'success' => (object)[
    'message' => 'Record inserted.'
  ]
];


# SCENARIO 3.1 - POST
# INSERT RECORD SQL - ERROR
$postRecordResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'post/record/',
  'error' => (object)[
    'code' => (string)'ERR-000',
    'message' => 'Record not inserted.'
  ]
];


######################################################################
######################################################################
######################################################################


# SCENARIO 4.0 - PUT
# UPDATE RECORD SQL - UPDATE table SET status = 'pending' WHERE id = 1001
$putRecordResponse_Success = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'put/record/1001',
  'success' => (object)[
    'message' => 'Record updated.'
  ]
];



# SCENARIO 4.1 - PUT
# UPDATE RECORD SQL - ERROR
$putRecordResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'put/record/1001',
  'error' => (object)[
    'code' => (string)'ERR-000',
    'message' => 'Record not updated.'
  ]
];


######################################################################
######################################################################
######################################################################


# SCENARIO 5.0 - DELETE
# DELETE RECORD SQL - DELETE FROM table WHERE id = 1001
$deleteRecordResponse_Success = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'delete/record/1001',
  'success' => (object)[
    'message' => 'Record deleted.'
  ]
];



# SCENARIO 5.1 - DELETE
# DELETE RECORD SQL - ERROR
$putRecordResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'delete/record/1001',
  'error' => (object)[
    'code' => (string)'ERR-000',
    'message' => 'Record not deleted.'
  ]
];


######################################################################
######################################################################
######################################################################


# SCENARIO 6.0 - GET/POST/PUT/DELETE
# HTTP ERROR
$httpServerResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'any/wrong/url/path/',
  'error' => (object)[
    'code' => (string)'404',
    'message' => (string)'Http error. End point not found.'
  ],
];




# SCENARIO 7.0 - GET/POST/PUT/DELETE
# DATABASE ERROR
$dbServerResponse_Error = 
  (object)[
  'apiVersion' => (string)'4.0',
  'context' => (string)'get/records/',
  'error' => (object)[
    'code' => (string)'ERR-000',
    'message' => (string)'Database error.'
  ],
];


######################################################################
######################################################################
######################################################################


# Set JSON Header...
header('Content-type:application/json;charset=utf-8');

print_r(json_encode($getRecordsResponse_Success));


?>

下面是Ajax中如何处理成功和错误响应的

GET请求

// ERROR HANDLER
if (response.error) {
  // DEBUG
  console.warn('(ER) - AJAX - SERVER ERROR: ', response.error.message);
}

// SUCCESS HANDLER
if (response.status == 'OK') {
  // DEBUG
  console.info('(OK) - AJAX - SERVER SUCCESS: ', response.data);
}

发布/放置/删除请求

// ERROR HANDLER
if (response.error) {
  // DEBUG
  console.warn('(ER) - AJAX - SERVER ERROR: ', response.error.message);
}

// SUCCESS HANDLER
if (response.success) {
  // DEBUG
  console.info('(OK) - AJAX - SERVER SUCCESS: ', response.success.message);
}